CREATE API INTEGRATION¶

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

API 集成对象存储有关 HTTPS 代理服务的信息，包括以下信息：

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

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

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

当此云用户被授予适当权限后，Snowflake 可以使用此用户访问代理服务（云平台的本地 HTTPS 代理服务，例如 Amazon API Gateway 实例）。

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

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

语法¶

每个云平台的语法都不同。

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

请注意，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 不应放在引号中。

必填参数¶

对于 Amazon API Gateway¶

integration_name

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

provider_info

指定 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。

iam_role

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

api_key

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

ENABLED = < TRUE | FALSE >

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

该值不区分大小写。

默认为 TRUE。

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

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

对于 Azure API Management 服务¶

integration_name

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

tenant_id

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

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

azure_application_id

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

api_key

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

ENABLED = < TRUE | FALSE >

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

该值不区分大小写。

默认为 TRUE。

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

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

对于 Google Cloud API Gateway¶

integration_name

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

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)>`_

ENABLED = < TRUE | FALSE >

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

该值不区分大小写。

默认为 TRUE。

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

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

可选参数¶

这些可选参数适用于以下各项：

Amazon API Gateway。
Azure API Management 服务。
Google Cloud API Gateway。

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

外部函数的描述。

访问控制要求¶

用于执行此 SQL 命令的角色必须至少具有以下权限：

权限	对象	备注
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> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

示例¶

此示例显示创建 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