CREATE API INTEGRATION¶

Creates a new API integration object in the account, or replaces an existing API integration.

An API integration object stores information about an HTTPS proxy service, including information about:

The cloud platform provider (e.g. Amazon AWS).

The type of proxy service (in case the cloud platform provider offers more than one type of proxy service).

The identifier and access credentials for a cloud platform role that has sufficient privileges to use the proxy service. For example, on AWS, the role’s ARN (Amazon resource name) serves as the identifier and access credentials.

When this cloud user is granted appropriate privileges, Snowflake can use this user to access resources on the proxy service (an instance of the cloud platform’s native HTTPS proxy service, for example, an instance of an Amazon API Gateway).

An API integration object also specifies allowed (and optionally blocked) endpoints and resources on those proxy services.

See also:: ALTER API INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS , Writing External Functions , CREATE EXTERNAL FUNCTION

Syntax¶

The syntax is different for each cloud platform.

For Amazon API Gateway¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }
    API_AWS_ROLE_ARN = '<iam_role>'
    [ API_KEY = '<api_key>' ]
    API_ALLOWED_PREFIXES = ('<...>')
    [ API_BLOCKED_PREFIXES = ('<...>') ]
    ENABLED = { TRUE | FALSE }
    [ COMMENT = '<string_literal>' ]
    ;

Copy

Note that aws_api_gateway or aws_private_api_gateway or aws_gov_api_gateway or aws_gov_private_api_gateway should not be in quotation marks.

For Azure API Management¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = azure_api_management
    AZURE_TENANT_ID = '<tenant_id>'
    AZURE_AD_APPLICATION_ID = '<azure_application_id>'
    [ API_KEY = '<api_key>' ]
    API_ALLOWED_PREFIXES = ( '<...>' )
    [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
    ENABLED = { TRUE | FALSE }
    [ COMMENT = '<string_literal>' ]
    ;

Copy

Note that azure_api_management should not be in quotation marks.

For Google Cloud API Gateway¶

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
    API_PROVIDER = google_api_gateway
    GOOGLE_AUDIENCE = '<google_audience_claim>'
    API_ALLOWED_PREFIXES = ( '<...>' )
    [ API_BLOCKED_PREFIXES = ( '<...>' ) ]
    ENABLED = { TRUE | FALSE }
    [ COMMENT = '<string_literal>' ]
    ;

Copy

Note that google_api_gateway should not be in quotation marks.

Required Parameters¶

For Amazon API Gateway¶

integration_name

Specifies the name of the API integration. This name follows the rules for Object Identifiers. The name should be unique among API integrations in your account.

provider_info

Specifies the HTTPS proxy service type. Valid values are:

aws_api_gateway: for Amazon API Gateway using regional endpoints.

aws_private_api_gateway: for Amazon API Gateway using private endpoints.

aws_gov_api_gateway: for Amazon API Gateway using U.S. government GovCloud endpoints.

aws_gov_private_api_gateway: for Amazon API Gateway using U.S. government GovCloud endpoints that are also private endpoints.

iam_role

For Amazon AWS, this is the ARN (Amazon resource name) of a cloud platform role.

api_key

The API key (also called a “subscription key”).

ENABLED = < TRUE | FALSE >

Specifies whether this API integration is enabled or disabled. If the API integration is disabled, any external function that relies on it will not work.

The value is case-insensitive.

The default is TRUE.

API_ALLOWED_PREFIXES = (...)

Explicitly limits external functions that use the integration to reference one or more HTTPS proxy service endpoints (e.g. Amazon API Gateway) and resources within those proxies. Supports a comma-separated list of URLs, which are treated as prefixes (for details, see below).

Each URL in API_ALLOWED_PREFIXES = (...) is treated as a prefix. For example, if you specify:

https://xyz.amazonaws.com/production/

that means all resources under

https://xyz.amazonaws.com/production/

are allowed. For example the following is allowed:

https://xyz.amazonaws.com/production/ml1

To maximize security, you should restrict allowed locations as narrowly as practical.

For Azure API Management Service¶

integration_name

Specifies the name of the API integration. This name follows the rules for Object Identifiers. The name should be unique among API integrations in your account.

tenant_id

Specifies the ID for your Office 365 tenant that all Azure API Management instances belong to. An API integration can authenticate to only one tenant, and so the allowed and blocked locations must refer to API Management instances that all belong to this tenant.

To find your tenant ID, log into the Azure portal and click Azure Active Directory » Properties. The tenant ID is displayed in the Tenant ID field.

azure_application_id

The “Application (client) id” of the Azure AD (Active Directory) app for your remote service. If you followed the instructions in Creating External Functions on Microsoft Azure, then this is the Azure Function App AD Application ID that you recorded in the worksheet in those instructions.

api_key

The API key (also called a “subscription key”).

ENABLED = < TRUE | FALSE >

Specifies whether this API integration is enabled or disabled. If the API integration is disabled, any external function that relies on it will not work.

The value is case-insensitive.

The default is TRUE.

API_ALLOWED_PREFIXES = (...)

Explicitly limits external functions that use the integration to reference one or more HTTPS proxy service endpoints (e.g. Azure API Management services) and resources within those proxies. Supports a comma-separated list of URLs, which are treated as prefixes (for details, see below).

Each URL in API_ALLOWED_PREFIXES = (...) is treated as a prefix. For example, if you specify:

https://my-external-function-demo.azure-api.net/my-function-app-name

that means all resources under

https://my-external-function-demo.azure-api.net/my-function-app-name

are allowed. For example the following is allowed:

https://my-external-function-demo.azure-api.net/my-function-app-name/my-http-trigger-function

To maximize security, you should restrict allowed locations as narrowly as practical.

For Google Cloud API Gateway¶

integration_name

Specifies the name of the API integration. This name follows the rules for Object Identifiers. The name should be unique among API integrations in your account.

google_audience

This is used as the audience claim when generating the JWT (JSON Web Token) to authenticate to the Google API Gateway. For more information about authenticating with Google, please see the Google service account authentication documentation.

ENABLED = < TRUE | FALSE >

Specifies whether this API integration is enabled or disabled. If the API integration is disabled, any external function that relies on it will not work.

The value is case-insensitive.

The default is TRUE.

API_ALLOWED_PREFIXES = (...)

Explicitly limits external functions that use the integration to reference one or more HTTPS proxy service endpoints (e.g. Google Cloud API Gateways) and resources within those proxies. Supports a comma-separated list of URLs, which are treated as prefixes (for details, see below).

Each URL in API_ALLOWED_PREFIXES = (...) is treated as a prefix. For example, if you specify:

https://my-external-function-demo.uc.gateway.dev/x

that means all resources under

https://my-external-function-demo.uc.gateway.dev/x

are allowed. For example the following is allowed:

https://my-external-function-demo.uc.gateway.dev/x/y

To maximize security, you should restrict allowed locations as narrowly as practical.

Optional Parameters¶

These optional parameters apply to each of the following:

Amazon API Gateway.
Azure API Management Service.
Google Cloud API Gateway.

API_BLOCKED_PREFIXES = (...)

Lists the endpoints and resources in the HTTPS proxy service that are not allowed to be called from Snowflake.

The possible values for locations follow the same rules as for API_ALLOWED_PREFIXES above.

API_BLOCKED_PREFIXES takes precedence over API_ALLOWED_PREFIXES. If a prefix matches both, then it is blocked. In other words, Snowflake allows all values that match API_ALLOWED_PREFIXES except values that also match API_BLOCKED_PREFIXES.

If a value is outside API_ALLOWED_PREFIXES, you do not need to explicitly block it.

COMMENT = '<string_literal>'

A description of the external function.

Access Control Requirements¶

A role used to execute this SQL command must have the following privileges at a minimum:

Privilege	Object	Notes
CREATE INTEGRATION	Account	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

Usage Notes¶

Only Snowflake roles with OWNERSHIP or USAGE privileges on the API integration can use the API integration directly (e.g. by creating an external function that specifies that API integration).
An API integration object is tied to a specific cloud platform account and role within that account, but not to a specific HTTPS proxy URL. You can create more than one instance of an HTTPS proxy service in a cloud provider account, and you can use the same API integration to authenticate to multiple proxy services in that account.
Your Snowflake account can have multiple API integration objects, for example, for different cloud platform accounts.
Multiple external functions can use the same API integration object, and thus the same HTTPS proxy service.
Regarding metadata:

Attention

Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata Fields in Snowflake.
CREATE OR REPLACE <object> statements are atomic. That is, when an object is replaced, the old object is deleted and the new object is created in a single transaction.

Examples¶

This example shows creation of an API integration and use of that API integration in a subsequent CREATE EXTERNAL FUNCTION statement:

create or replace api integration demonstration_external_api_integration_01
    api_provider=aws_api_gateway
    api_aws_role_arn='arn:aws:iam::123456789012:role/my_cloud_account_role'
    api_allowed_prefixes=('https://xyz.execute-api.us-west-2.amazonaws.com/production')
    enabled=true;

create or replace external function local_echo(string_col VARCHAR)
    returns variant
    api_integration = demonstration_external_api_integration_01
    as 'https://xyz.execute-api.us-west-2.amazonaws.com/production/remote_echo';

Copy