CREATE API INTEGRATION | Snowflake Documentation (original) (raw)

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

An API integration object stores information about a service reached via HTTPS API, including information about some of the following:

See also:

ALTER API INTEGRATION , DROP INTEGRATION ,SHOW INTEGRATIONS , Writing external functions ,CREATE EXTERNAL FUNCTION

Syntax

The syntax is different for each external API.

For Amazon API Gateway

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

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

For Azure API Management

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

Note that azure_api_management should not be in quotation marks.

For Google Cloud API Gateway

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

Note that google_api_gateway should not be in quotation marks.

For Git repository

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] API_PROVIDER = git_https_api API_ALLOWED_PREFIXES = ('<...>') [ API_BLOCKED_PREFIXES = ('<...>') ] [ ALLOWED_AUTHENTICATION_SECRETS = ( { [, , ... ] | all | none } ) ] ENABLED = { TRUE | FALSE } [ COMMENT = '' ] ;

Note that git_https_api should not be in quotation marks.

Required parameters

For Amazon API Gateway

_integrationname_

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.

API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }

Specifies the HTTPS proxy service type. Valid values are:

API_AWS_ROLE_ARN = _iamrole_

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

API_ALLOWED_PREFIXES = (...)

Explicitly limits external functions that use the integration to reference one or more HTTPS proxy service endpoints (such as 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.

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.

For Azure API Management Service

_integrationname_

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.

API_PROVIDER = azure_api_management

Specifies that this integration is used with Azure API Management services. Do not use quotation marks around azure_api_management.

AZURE_TENANT_ID = _tenantid_

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, sign in to the Azure portal and select Azure Active Directory » Properties. The tenant ID is displayed in the Tenant ID field.

AZURE_AD_APPLICATION_ID = _azureapplicationid_

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_ALLOWED_PREFIXES = (...)

Explicitly limits external functions that use the integration to reference one or more HTTPS proxy service endpoints (such as 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.

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.

For Google Cloud API Gateway

_integrationname_

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.

API_PROVIDER = google_api_gateway

Specifies that this integration is used with Google Cloud. The only valid value for this purpose is google_api_gateway. The value must not be in quotation marks.

GOOGLE_AUDIENCE = _googleaudience_

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 accountauthentication documentation.

API_ALLOWED_PREFIXES = (...)

Explicitly limits external functions that use the integration to reference one or more HTTPS proxy service endpoints (such as 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.

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.

For Git repository

For an example, see Create an API integration for interacting with the repository API.

_integrationname_

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.

API_PROVIDER = git_https_api

Specifies that this integration is used with CREATE GIT REPOSITORY to create anintegration with a Git repository. The only valid value for this purpose is git_https_api. The value must not be in quotation marks.

API_ALLOWED_PREFIXES = (...)

Explicitly limits requests that use the integration to reference one or more HTTPS endpoints and resources beneath those endpoints. Supports a comma-separated list of URLs, which are treated as prefixes.

Snowflake supports any HTTPS Git repository URL. For example, you can specify a custom URL to a corporate Git server within your own domain.

https://example.com/my-repo

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

https://github.com/my-account

With this prefix, all resources under that URL are allowed. For example, the following is allowed:

https://github.com/my-account/myproject

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

ENABLED = { TRUE | FALSE }

Specifies whether this API integration is enabled or disabled. If the API integration is disabled, the Git repository will not be accessible.

The value is case-insensitive.

The default is TRUE.

Optional parameters

For all integrations

API_KEY = _apikey_

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

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 = '_stringliteral_'

A description of the integration.

For Git repository

In addition to parameters for all integrations, the following parameters are available when you use the integration to connect to a remote Git repository. This would be the case when you’re setting the integration’s API_PROVIDER parameter togit_https_api.

ALLOWED_AUTHENTICATION_SECRETS = ( _secretname_ [, _secretname_ ... ] | all | none )

Specifies the secrets that UDF or procedure handler code can use when accessing the Git repository at the API_ALLOWED_PREFIXES value. You specify a secret from this list when specifying Git credentials with the GIT_CREDENTIALS parameter.

This parameter’s value must be one of the following:

The ALLOWED_API_AUTHENTICATION_INTEGRATIONS parameter can also specify allowed secrets. For more information, seeUsage notes.

For reference information about secrets, refer to CREATE SECRET.

Access control requirements

A role used to execute this operation must have the followingprivileges 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 onsecurable objects, see Overview of Access Control.

Usage notes

Examples

Amazon API Gateway

The following 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';

Git repository

For an example of an API integration used to integrate a Git repository, see Create an API integration for interacting with the repository API.