CREATE API INTEGRATION

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

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

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

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

  • 具有足够权限使用服务的外部服务的标识符和访问凭据。例如，在 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 存储库

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

请注意，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 存储库

有关示例，请参阅 创建用于与存储库 API 进行交互的 API 集成。

integration_name

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

API_PROVIDER = git_https_api

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

API_ALLOWED_PREFIXES = (...)

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

Snowflake 支持使用以下 URLs：

  • https://github.com (https://github.com)

  • https://gitlab.com (https://gitlab.com)

  • https://bitbucket.org (https://bitbucket.org)

  • https://git-codecommit.amazonaws.com (https://git-codecommit.amazonaws.com)

  • https://dev.azure.com (https://dev.azure.com)

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

https://github.com/my-account

这意味着

https://github.com/my-account

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

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

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

ENABLED = { TRUE | FALSE }

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

该值不区分大小写。

默认为 TRUE。

可选参数

API_BLOCKED_PREFIXES = (...)

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

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

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

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

API_KEY = api_key

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。

COMMENT = 'string_literal'

集成的描述。

访问控制要求

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

权限

对象

备注

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 中的元数据字段。

  • 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 集成示例，请参阅 创建用于与存储库 API 进行交互的 API 集成。

语言: 中文