CREATE API INTEGRATION¶

在账户中创建新的 API 集成对象，或替换现有的 API 集成。

API 集成对象存储有关通过 HTTPS API 到达的服务的信息，包括关于以下部分内容的信息：

云平台提供商（如 Amazon AWS）。

Git 存储库 API。

服务类型（例如当云平台提供商提供多种类型的代理服务时）。

具有足够权限使用服务的外部服务的标识符和访问凭据。例如，在 AWS 上，角色的 ARN (Amazon Resource Name) 可作为标识符和访问凭据。

当此用户被授予适当的权限时，Snowflake 可以使用此用户访问资源。例如，这可能是云平台原生 HTTPS 代理服务的实例，例如 Amazon API Gateway 的实例。

API 集成对象还指定了这些服务上允许（和可选阻止）的端点和资源。

另请参阅：: ALTER API INTEGRATION、DROP INTEGRATION、SHOW INTEGRATIONS、编写外部函数、CREATE EXTERNAL FUNCTION

语法¶

每个外部 API 的语法都不同。

对于 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 = ('<...>')
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

请注意，aws_api_gateway 或 aws_private_api_gateway 或 aws_gov_api_gateway 或 aws_gov_private_api_gateway 不应放在引号中。

对于 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

请注意，azure_api_management 不应放在引号中。

对于 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

请注意，google_api_gateway 不应放在引号中。

对于 Git 存储库¶

与 Git 存储库集成时，您可以使用个人访问令牌或 OAuth。

备注

仅当存储库托管在 github.com 上时，才能在工作区中将 OAuth 用于 Git 存储库。有关更多信息，请参阅创建 Git 工作区。

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

Copy

CREATE [ OR REPLACE ] API INTEGRATION [ IF NOT EXISTS ] <integration_name>
  API_PROVIDER = git_https_api
  API_ALLOWED_PREFIXES = ('https://github.com/<...>')
  [ API_BLOCKED_PREFIXES = ('<...>') ]
  API_USER_AUTHENTICATION = (
    TYPE = snowflake_github_app
  )
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]
  ;

Copy

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

Copy

请注意，git_https_api 不应放在引号中。

必填参数¶

对于 Amazon API Gateway¶

integration_name

指定 API 集成的名称。此名称遵循对象标识符的规则。该名称在您账户中的 API 集成中必须是唯一的。

API_PROVIDER = { aws_api_gateway | aws_private_api_gateway | aws_gov_api_gateway | aws_gov_private_api_gateway }

指定 HTTPS 代理服务类型。有效值为：

aws_api_gateway：用于使用区域端点的 Amazon API Gateway。

aws_private_api_gateway：用于使用私有端点的 Amazon API Gateway。

aws_gov_api_gateway：用于使用美国政府 GovCloud 端点的 Amazon API Gateway。

aws_gov_private_api_gateway：用于使用美国政府 GovCloud 端点（也是专用端点）的 Amazon API Gateway。

API_AWS_ROLE_ARN = iam_role

对于 Amazon AWS，这是云平台角色的 ARN (Amazon Resource Name)。

API_ALLOWED_PREFIXES = (...)

对使用集成引用一个或多个 HTTPS 代理服务端点（例如 Amazon API Gateway）和这些代理中的资源的外部函数进行显式限制。支持逗号分隔的 URLs 列表，它们会被视为前缀（有关详细信息，请参阅下文）。

API_ALLOWED_PREFIXES = (...) 中的每个 URL 都被视为前缀。例如，如果指定：

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

这意味着

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

下的所有资源都是允许的。例如，允许使用以下 URL：

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

为了最大限度地提高安全性，应尽可能对允许的位置进行严格限制。

ENABLED = { TRUE | FALSE }

指定是启用还是禁用此 API 集成。如果禁用 API 集成，则依赖它的任何外部功能都将无法正常工作。

该值不区分大小写。

默认为 TRUE。

对于 Azure API Management 服务¶

integration_name

指定 API 集成的名称。此名称遵循对象标识符的规则。该名称在您账户中的 API 集成中应是唯一的。

API_PROVIDER = azure_api_management

指定此集成与 Azure API Management 服务一起使用。不要在 azure_api_management 周围使用引号。

AZURE_TENANT_ID = tenant_id

指定所有 Azure ID Management 实例所属的 Office 365 租户的 API。一个 API 集成只能对一个租户进行身份验证，因此允许和阻止的位置必须引用同属于此租户的 API Management 实例。

要查找租户 ID，请登录 Azure 门户并选择 Azure Active Directory » Properties。租户 ID 将显示在 Tenant ID 字段中。

AZURE_AD_APPLICATION_ID = azure_application_id

远程服务的 Azure AD (Active Directory) 应用程序的“应用程序（客户端）ID”。如果您按照在 Microsoft Azure 上创建外部函数中的说明进行了操作，那么这就是您在这些说明的工作表中记录的 Azure Function App AD Application ID。

API_ALLOWED_PREFIXES = (...)

对使用集成引用一个或多个 HTTPS 代理服务端点（例如 Azure API Management 服务）和这些代理中的资源的外部函数进行显式限制。支持逗号分隔的 URLs 列表，它们会被视为前缀（有关详细信息，请参阅下文）。

API_ALLOWED_PREFIXES = (...) 中的每个 URL 都被视为前缀。例如，如果指定：

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

这意味着

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

下的所有资源都是允许的。例如，允许使用以下 URL：

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

为了最大限度地提高安全性，应尽可能对允许的位置进行严格限制。

ENABLED = { TRUE | FALSE }

指定是启用还是禁用此 API 集成。如果禁用 API 集成，则依赖它的任何外部功能都将无法正常工作。

该值不区分大小写。

默认为 TRUE。

对于 Google Cloud API Gateway¶

integration_name

指定 API 集成的名称。此名称遵循对象标识符的规则。该名称在您账户中的 API 集成中应是唯一的。

API_PROVIDER = google_api_gateway

指定此集成与 Google Cloud 一起使用。此目的的唯一有效值是 google_api_gateway。值不能在引号中。

GOOGLE_AUDIENCE = google_audience

在生成 JWT（JSON 网络令牌）以对 Google API Gateway 进行身份验证时，这将用作受众声明。有关 Google 身份验证的更多信息，请参阅 Google 服务账户 ` 身份验证文档。<https://cloud.google.com/api-gateway/docs/authenticate-service-account#configure_auth (https://cloud.google.com/api-gateway/docs/authenticate-service-account#configure_auth)>`_

API_ALLOWED_PREFIXES = (...)

对使用集成引用一个或多个 HTTPS 代理服务端点（例如 Google Cloud API Gateway）和这些代理中的资源的外部函数进行显式限制。支持逗号分隔的 URLs 列表，它们会被视为前缀（有关详细信息，请参阅下文）。

API_ALLOWED_PREFIXES = (...) 中的每个 URL 都被视为前缀。例如，如果指定：

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

这意味着

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

下的所有资源都是允许的。例如，允许使用以下 URL：

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

为了最大限度地提高安全性，应尽可能对允许的位置进行严格限制。

ENABLED = { TRUE | FALSE }

指定是启用还是禁用此 API 集成。如果禁用 API 集成，则依赖它的任何外部功能都将无法正常工作。

该值不区分大小写。

默认为 TRUE。

对于 Git 存储库¶

有关示例，请参阅设置 Snowflake 以使用 Git。

integration_name

指定 API 集成的名称。此名称遵循对象标识符的规则。该名称在您账户中的 API 集成中必须是唯一的。

API_PROVIDER = git_https_api

指定此集成与 CREATE GIT REPOSITORY 一起使用，以创建与远程 Git 存储库的集成。此目的的唯一有效值是 git_https_api。值不能在引号中。

API_ALLOWED_PREFIXES = (...)

对使用集成引用一个或多个 HTTPS 端点和这些端点下的资源的请求进行显式限制。支持逗号分隔的 URLs 列表，它们会被视为前缀。

备注

使用 OAuth 进行身份验证时，必须在允许的前缀的基础 URL 中指定 https://github.com。仅当存储库托管在 github.com 上时，才能在工作区中使用 OAuth 对 Git 存储库进行身份验证。

在大多数情况下，Snowflake 支持任何 HTTPS Git 存储库 URL。例如，您可以在自己的域内为企业 Git 服务器指定自定义 URL。

https://example.com/my-repo

API_ALLOWED_PREFIXES = (...) 中的每个 URL 都被视为前缀。例如，您可以指定以下内容：

https://github.com/my-account

如果使用此前缀，则允许使用 URL 下的所有资源。例如，允许使用以下函数：

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

为了最大限度地提高安全性，应尽可能对允许的位置进行严格限制。

ENABLED = { TRUE | FALSE }

指定是启用还是禁用此 API 集成。如果禁用 API 集成，则 Git 存储库将无法访问。

该值不区分大小写。

默认为 TRUE。

可选参数¶

适用于所有集成¶

API_KEY = api_key

API 密钥（也称为“订阅密钥”）。

API_BLOCKED_PREFIXES = (...)

列出了 HTTPS 代理服务中不允许从 Snowflake 调用的端点和资源。

位置的可能值遵循与上述 API_ALLOWED_PREFIXES 相同的规则。

API_BLOCKED_PREFIXES 优先于 API_ALLOWED_PREFIXES。如果某前缀与两者都匹配，则会被阻止。换句话说，Snowflake 允许所有与 API_ALLOWED_PREFIXES 匹配的值，但同时与 API_BLOCKED_PREFIXES 匹配的值除外。

如果某个值在 API_ALLOWED_PREFIXES 范围之外，则无需对其显式阻止。

COMMENT = 'string_literal'

集成的描述。

对于 Git 存储库¶

除了适用于所有集成的参数外，在使用集成连接到远程 Git 存储库时，还可使用以下参数，方法是将集成的 API_PROVIDER 参数设置为 git_https_api。

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

指定 UDF 或程序处理程序代码在以 API_ALLOWED_PREFIXES 值访问 Git 存储库时可以使用的密钥。使用 GIT_CREDENTIALS 参数指定 Git 凭据时，您从此列表中指定一个密钥。

此参数的值必须为以下值之一：

一个或多个完全限定 Snowflake 密钥名称，以允许任何列出的密钥。
（默认）:code:all 以允许任何密钥。
none，以禁止密钥。

ALLOWED_API_AUTHENTICATION_INTEGRATIONS 参数还可以指定允许的密钥。有关更多信息，请参阅使用说明。

有关密钥的参考信息，请参阅 CREATE SECRET。

API_USER_AUTHENTICATION = ( TYPE = snowflake_github_app )

为 OAuth 2.0 流程指定安全集成设置。值 snowflake_github_app 会将 OAuth 2.0 指定为 Snowflake 用于连接存储库的身份验证类型。

备注

仅当存储库托管在 github.com 上时，才能在工作区中将 OAuth 用于 Git 存储库。有关更多信息，请参阅创建 Git 工作区。

TLS_TRUSTED_CERTIFICATES = ( {secret_name} [, {secret_name} ... ] )

指定包含自签名证书的密钥，以便在通过专用链接向 Git 存储库服务器进行身份验证时使用。仅当证书是自签名，而不是由证书颁发机构签名时，才需要此参数。

此参数的值必须是一个或多个完全限定的 Snowflake 密钥名称。密钥必须是通用字符串类型，其 SECRET_STRING 值为 Base64 编码的证书数据。

USE_PRIVATELINK_ENDPOINT = { TRUE | FALSE }

指定此 API 集成是否仅用于通过专用连接配置通过出站专用链接连接对远程 Git 存储库的访问。

对于公共 Git 服务器，此参数必须设置为 :code:`FALSE`（默认值）。

默认为 FALSE。

访问控制要求¶

用于执行此操作的角色必须至少具有以下权限：

权限	对象	备注
CREATE INTEGRATION	账户	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

有关创建具有指定权限集的自定义角色的说明，请参阅创建自定义角色。

有关对安全对象执行 SQL 操作的相应角色和权限授予的一般信息，请参阅访问控制概述。

使用说明¶

只有具有 API 集成的 OWNERSHIP 或 USAGE 权限的 Snowflake 角色才可以直接使用 API 集成（例如，通过创建指定该 API 集成的外部函数）。
API 集成对象与特定云平台账户及其账户内的角色相关联，但不与特定 HTTPS 代理 URL 相关联。您可以在一个云提供商账户中创建多个 HTTPS 代理服务实例，也可以使用相同的 API 集成对该账户中的多个代理服务进行身份验证。
您的 Snowflake 账户可以拥有多个 API 集成对象，例如，不同的云平台账户。
多个外部函数可以使用相同的 API 集成对象，从而使用相同的 HTTPS 代理服务。
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

OR REPLACE 和 IF NOT EXISTS 子句互斥。它们不能同时用于同一条语句中。
CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

示例¶

Amazon API Gateway¶

以下示例显示创建 API 集合以及在随后的 CREATE EXTERNAL FUNCTION 语句中使用该 API 集成：

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

Git 存储库¶

有关用于集成 Git 存储库的 API 集成示例，请参阅设置 Snowflake 以使用 Git。