创建和使用外部访问集成¶

要启用对特定外部网络位置的访问，请创建外部访问集成以指定网络规则列表，从而指定您获准使用的外部位置列表和密钥列表。当使用 CREATE FUNCTION 或 CREATE PROCEDURE 创建 UDF 或过程时，通过使用 EXTERNAL_ACCESS_INTEGRATIONS 子句来引用此集成，可以允许处理程序代码使用该密钥对外部位置进行身份验证。

管理员可以使用 EXTERNAL_ACCESS_HISTORY 视图来监控对外部网络位置的请求。

有关可能用于设置和使用外部访问的端到端代码示例序列，请参阅外部网络访问示例。

根据以下步骤设置从 UDF 或过程访问外部网络位置。

创建网络规则以表示外部网络位置。
创建密钥来保存凭据。
创建外部访问集成，聚合密钥和网络规则，以便处理程序在访问外部位置时可以使用它们。
创建 UDF 或过程，并将 EXTERNAL_ACCESS_INTEGRATIONS 参数设置为集成的名称作为值。这给予函数或过程访问外部网络位置和使用由集成中的网络规则和密钥指定的凭据的权限。

可以单独将 SECRET 参数设置为集成中包含的密钥的名称，以便可以从处理程序代码访问密钥的内容。

在函数或过程处理程序代码中，访问集成中包含的网络规则中指定的外部网络位置。访问未由允许的网络规则指定的网络位置的尝试将被拒绝。

创建网络规则以表示外部网络位置¶

可以使用 CREATE NETWORK RULE 命令创建表示外部网络位置和访问限制的网络规则。例如，网络规则指定网络标识符，诸如主机名和与网络的通信方向（入口或出口）。

为了支持访问外部网络，管理员将在创建 :ref:` 外部访问集成 <label-creating_using_external_access_integration_access_integration>` 时包括该规则。集成中包含的每个规则都指定允许函数或过程访问的外部网络位置。

创建用于外部访问集成的网络规则时，请指定以下内容：

EGRESS 作为 MODE 参数值。
HOST_PORT 作为 TYPE 参数值。
VALUE_LIST 参数中外部位置的端点。
（可选）带有外部位置端点名称的端口号。如果省略了端口号，Snowflake 将使用默认端口号进行外部访问，即 443。

例如，如果端点需要端口 80，则 VALUE_LIST 参数可能如下所示：
```
VALUE_LIST = ('example.com:80')
```
Copy

访问控制¶

为了安全起见，Snowflake 要求在创建网络规则时，您必须使用符合以下条件的角色：

对保留规则的架构具有 CREATE NETWORK RULE 权限。

示例¶

以下示例中的代码创建一个网络规则，该规则针对对 Google Translation API 的出站请求调用 google_apis_network_rule。

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

Copy

创建表示凭据的密钥¶

可以使用 CREATE SECRET 创建表示对外部网络位置进行身份验证所需凭据的密钥。例如，密钥可以包含诸如用户名和密码之类的凭据。

对于访问支持 OAuth 的外部网络位置，最佳实践是让密码包含对安全集成的引用，该安全集成包含 OAuth 流所需的值，如客户端 ID、客户端密钥、令牌端点等。

该密钥将按以下方式使用：

由管理员在创建 :ref:` 外部访问集成 <label-creating_using_external_access_integration_access_integration>` 时使用。

在创建集成时，管理员将指定开发者在创建使用集成的函数或过程时可能在处理程序代码中使用的密钥。
由开发者在创建 UDF 或过程处理程序时使用。

开发者将指定允许的密钥，该密钥包含处理程序代码在向外部位置发出请求时可用于进行身份验证的凭据。在编写处理程序时，开发者可以使用 Snowflake API 来检索密钥包含的凭据，而不是将凭据作为字面量值包含在处理程序代码中。

备注

对于需要刷新令牌的 OAuth 密钥，可以通过多种方式获取令牌，包括通过 Snowflake 中提供的系统函数。有关示例，请参阅访问 Google Translate API。

访问控制¶

为了安全起见，Snowflake 要求您在创建密钥时必须使用符合以下条件的角色：

对保留密钥的架构具有 CREATE SECRET 权限。

示例¶

以下示例中的代码创建一个名为 oauth_token 的密钥，该密钥指定一个安全集成（由 google_translate_oauth 表示），其中包含使用 OAuth 进行身份验证所需的值。

有关更完整的示例（包括用于创建安全集成的代码），请参阅外部网络访问示例。

CREATE OR REPLACE SECRET oauth_token
  TYPE = OAUTH2
  API_AUTHENTICATION = google_translate_oauth
  OAUTH_REFRESH_TOKEN = 'my-refresh-token';

Copy

小技巧

在此预览版中，当只想将 API 密钥用作凭据时，可以将 TYPE 指定为 GENERIC_STRING。

CREATE OR REPLACE SECRET bp_maps_api
  TYPE = GENERIC_STRING
  SECRET_STRING = 'replace-with-your-api-key';

Copy

创建外部访问集成¶

可以使用 CREATE EXTERNAL ACCESS INTEGRATION 命令创建外部访问集成，该集成汇总允许的网络规则（表示外部网络位置）和允许的密钥（表示用于身份验证的凭据），以便与 UDFs 和过程一起使用。

具体而言，外部访问集成指定引用集成的 UDFs 和过程可以使用的那些网络规则和密钥。

管理员将使用外部访问集成来管理从 UDFs 和过程对外部网络位置的访问。集成只指定允许引用集成的 UDFs 和过程使用的位置和凭据。管理员还可以启用或禁用集成以管理对外部位置的访问。

访问控制¶

为了安全起见，Snowflake 要求您在创建外部访问集成时必须使用符合以下条件的角色：

账户的 CREATE INTEGRATION 权限。
对集成使用的任何密钥具有 USAGE 权限，以及对密钥架构具有 USAGE 权限。

示例¶

以下示例中的代码创建一个名为 google_apis_access_integration 的外部访问集成。该集成指定 google_apis_network_rule 网络规则（表示网络位置）和 oauth_token 密钥（表示凭据）。

有关此规则和密钥的详细信息，请参阅创建网络规则以表示外部网络位置和创建表示凭据的密钥。

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

Copy

在函数或过程中使用外部访问集成¶

使用 CREATE FUNCTION 或 CREATE PROCEDURE 命令创建 UDF 或过程时，可以按如下方式启用对外部网络位置的访问：

包括 EXTERNAL_ACCESS_INTEGRATIONS 参数，将其值设置为一个或多个集成。

您指定的每个集成都允许访问该集成指定的外部网络位置和密钥。
包括 SECRETS 参数，将其值设置为一个或多个密钥以及将用于从处理程序代码访问它们的名称。

您指定为值的密钥也必须在外部访问集成中指定。
在处理程序代码中，访问密钥以检索用于对外部网络位置进行身份验证的凭据。

备注

始终使用 Snowflake 密钥来表示凭据，而不要将凭据作为字面量值包含在代码中。除了保护凭据之外，使用密钥还可以审核和管理凭据的使用，因为只有获授密钥的 READ 权限的用户可以在 UDF 或过程中使用包含密钥的集成。

Snowflake 限制了可以从特定 UDF 建立的连接总数。为了避免遇到资源耗尽问题，请尽可能多地重用连接。可以通过在 UDF 初始化期间创建一次 TCP 客户端或会话来实现这一点，然后在 UDF 处理程序中为其余的查询使用它。

访问控制¶

为了安全起见，Snowflake 要求您在创建 UDF 或过程时必须使用符合以下条件的角色：

对其引用的任意密钥具有 READ 权限，以及对密钥架构具有 USAGE 权限。
对其引用的任意集成具有 USAGE 权限。

具备这些权限后，管理员能够管理可以启用外部访问的用户组。有关更多信息，请参阅 GRANT <privileges> 和访问控制权限。

示例¶

以下示例中的代码创建一个名为 google_translate_python 的 UDF，指定一个名为 google_apis_access_integration 的外部访问集成（有关详细信息，请参阅创建外部访问集成）。该集成指定允许引用该集成的 UDF 使用的网络规则（表示外部网络位置）和密钥（表示凭据）。有关此规则和密钥的详细信息，请参阅创建网络规则以表示外部网络位置和创建表示凭据的密钥。

Python 处理程序代码使用 _snowflake.get_oauth_access_token 函数从密钥中检索 OAuth 令牌，然后使用该令牌对外部位置进行身份验证。处理程序代码可能会向指定的 URL 发出请求，因为该 URL 的主机列在集成指定的网络规则中。

CREATE OR REPLACE FUNCTION google_translate_python(sentence STRING, language STRING)
RETURNS STRING
LANGUAGE PYTHON
RUNTIME_VERSION = 3.8
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']
$$;

Copy