CREATE EXTERNAL ACCESS INTEGRATION¶

创建外部访问集成，以便从 UDF 或过程处理程序访问外部网络位置。

另请参阅：: ALTER EXTERNAL ACCESS INTEGRATION、DROP INTEGRATION、SHOW INTEGRATIONS、DESCRIBE INTEGRATION

语法¶

CREATE [ OR REPLACE ] EXTERNAL ACCESS INTEGRATION <name>
  ALLOWED_NETWORK_RULES = ( <rule_name_1> [, <rule_name_2>, ... ] )
  [ ALLOWED_API_AUTHENTICATION_INTEGRATIONS = { ( <integration_name_1> [, <integration_name_2>, ... ] ) | none } ]
  [ ALLOWED_AUTHENTICATION_SECRETS = { ( <secret_name_1> [, <secret_name_2>, ... ] ) | all | none } ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]

必填参数¶

name

外部访问集成的标识符。

标识符值必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如 "My object"）。放在双引号内的标识符区分大小写。

有关更多详细信息，请参阅标识符要求。

ALLOWED_NETWORK_RULES = (rule_name [ , rule_name ... ])

指定允许的网络规则。只能指定出口规则。

ENABLED = { TRUE | FALSE }

指定是启用还是禁用此集成。如果禁用了集成，任何依赖集成的处理程序代码都将无法到达外部网络位置。

该值不区分大小写。

默认为 TRUE。

可选参数¶

ALLOWED_API_AUTHENTICATION_INTEGRATIONS = ( integration_name_1 [, integration_name_2, ... ] ) | none

指定安全集成，其 OAuth 授权服务器发布了 UDF 或程序所使用的密钥。安全集成必须是用于外部 API 集成的类型。

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

一个或多个 Snowflake 安全集成名称，以允许任何列出的集成。
none，以不允许集成。

此参数指定的安全集成 – 以及 ALLOWED_AUTHENTICATION_SECRETS 参数指定的密钥 – 是允许在 UDF 或使用此外部访问集成的过程中使用密钥的方法。有关更多信息，请参阅使用说明。

有关安全集成的参考信息，请参阅 CREATE SECURITY INTEGRATION（外部 API 身份验证）。

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

指定 UDF 或过程处理程序代码在访问允许的网络规则中引用的外部网络位置时可以使用的密钥。

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

一个或多个 Snowflake 密钥名称，以允许列出的任何密钥。
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.
USAGE	密钥	对于集成引用的所有密钥都是必需的。
USAGE	架构	对于包含集成引用的任何密钥的所有架构都是必需的。
CREATE EXTERNAL ACCESS INTEGRATION	账户	授予创建外部访问集成的能力。此权限不授予创建其他类型集成的能力。

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

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

使用说明¶

您可以通过使用两个外部访问集成参数，允许 UDF 或过程使用密钥，具体用法如下所述。
- 使用 ALLOWED_AUTHENTICATION_SECRETS 参数。您可以将密钥指定为参数值，或将参数的值设置为 all，以允许处理程序代码使用任何密钥。
- 使用 ALLOWED_API_AUTHENTICATION_INTEGRATIONS 参数。当密钥本身指定名称也由该参数指定的安全集成时，允许使用密钥。密钥使用其 API_AUTHENTICATION 参数指定安全集成。换句话说，当密钥和外部访问集成都指定了安全集成时，允许将密钥用于指定外部访问集成的函数和过程。
请注意，这两个替代函数彼此独立运行。如果其中一个（或两个）参数允许使用密钥，则不管对另一个参数指定的值如何，都允许使用密钥。例如，将其中一个参数设置为 none 并不会阻止在处理程序代码中使用另一个参数指定的密钥。
虽然您可以使用主机名指定网络规则，但 Snowflake 会在 IP 粒度级别执行规则。Snowflake 不会检查您应用程序的流量，因此您有责任确保外部位置的主机具有真实的服务，并且无法连接到同一主机上的其他服务。与互联网端点通信时,您应尽可能使用 HTTPS 和 TLS 等安全协议。
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。
CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

示例¶

创建外部访问集成，提供对 Google 翻译 API 的访问。

有关更完整的示例，请参阅创建和使用外部访问集成。

创建一个代表凭据的密钥。

要创建密钥，必须为您分配一个具有当前架构 CREATE SECRET 权限的角色。有关此命令支持的其他类型的密钥，请参阅 CREATE SECRET。在此示例中，google_translate_oauth 表示安全集成。有关更多信息，请参阅 CREATE SECURITY INTEGRATION（外部 API 身份验证）。
```
CREATE OR REPLACE SECRET oauth_token
  TYPE = OAUTH2
  API_AUTHENTICATION = google_translate_oauth
  OAUTH_REFRESH_TOKEN = 'my-refresh-token';
```
向 developer 角色授予密钥的 READ 权限，以便 UDF 开发者可以使用它。

创建需要使用密钥的开发者所需具备的角色。
```
USE ROLE USERADMIN;
CREATE OR REPLACE ROLE developer;
```
向 developer 角色授予 READ 权限。
```
USE ROLE SECURITYADMIN;
GRANT READ ON SECRET oauth_token TO ROLE developer;
```

创建代表外部网络位置的网络规则。使用具有 CREATE NETWORK RULE 中所述权限的角色。

USE ROLE SYSADMIN;
CREATE OR REPLACE NETWORK RULE google_apis_network_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('translation.googleapis.com');

使用密钥和网络规则创建外部访问集成。

USE ROLE ACCOUNTADMIN;
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION google_apis_access_integration
  ALLOWED_NETWORK_RULES = (google_apis_network_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (oauth_token)
  ENABLED = true;

向 developer 角色授予集成的 USAGE 权限，以便 UDF 开发者可以使用它。
```
GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE developer;
```

创建一个 UDF google_translate_python，将指定文本翻译成指定语言的短语。有关更多信息，请参阅在函数或过程中使用外部访问集成。

USE ROLE developer;

CREATE OR REPLACE FUNCTION google_translate_python(sentence STRING, language STRING)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.10
HANDLER = 'get_translation'
EXTERNAL_ACCESS_INTEGRATIONS = (google_apis_access_integration)
PACKAGES = ('snowflake-snowpark-python','requests')
SECRETS = ('cred' = oauth_token )
AS
$$
import _snowflake
import requests
import json
session = requests.Session()
def get_translation(sentence, language):
  token = _snowflake.get_oauth_access_token('cred')
  url = "https://translation.googleapis.com/language/translate/v2"
  data = {'q': sentence,'target': language}
  response = session.post(url, json = data, headers = {"Authorization": "Bearer " + token})
  return response.json()['data']['translations'][0]['translatedText']
$$;

授予对 google_translate_python 函数的 USAGE 权限，以便具有相应用户角色的人可以调用它。
```
GRANT USAGE ON FUNCTION google_translate_python(string, string) TO ROLE user;
```

执行 google_translate_python 函数来翻译短语。

USE ROLE user;
SELECT google_translate_python('Happy Thursday!', 'zh-CN');

这会生成以下输出。

-------------------------------------------------------
| GOOGLE_TRANSLATE_PYTHON('HAPPY THURSDAY!', 'ZH-CN') |
-------------------------------------------------------
| 快乐星期四！                                          |
-------------------------------------------------------