使用 SQL 命令安装和配置连接器¶

设置 OAuth¶

您可以配置 Snowflake Connector for ServiceNow® 以使用 OAuth 对 ServiceNow 实例进行身份验证：

• 在 ServiceNow 中，您必须将实例设置为支持与 `代码许可流程`_搭配使用 OAuth。

• 在 Snowflake Connector for ServiceNow® 中：

  • 该连接器使用安全集成 TYPE = API_AUTHENTICATION 将 Snowflake 连接到 ServiceNow 实例。

    安全集成指定 ServiceNow OAuth 客户端 ID、客户端密钥以及端点 URL，用于对 ServiceNow 实例进行身份验证。

  • 该连接器使用 Snowflake 密钥对象来管理敏感信息，包括身份验证凭据。

    在使用 OAuth 进行身份验证的情况下，该连接器将 ServiceNow OAuth 刷新令牌、刷新令牌过期时间以及安全集成的名称存储在 Snowflake 密钥对象中。

要设置 Snowflake Connector for ServiceNow® 以使用 OAuth，请按照以下步骤操作：

1. 将 ServiceNow 实例配置为将 OAuth 与代码许可流程一起使用。

   • 如果 ServiceNow 实例已使用 OAuth 代码许可流程，并且您希望将该实例与 Snowflake Connector for ServiceNow® 一起使用，请记下与 OAuth 令牌对应的客户端 ID、客户端密钥和端点 URL。

     有关更多信息，请参阅 管理 OAuth 令牌 (https://docs.servicenow.com/bundle/washingtondc-platform-security/page/administer/security/task/t_ManageTokens.html)。记下此信息后，在下一步中创建安全集成。

   • 如果您要使用其他 ServiceNow 实例，请访问或创建实例，并将实例配置为使用 OAuth 与代码许可流程，如 设置 OAuth 和 `创建端点供客户端访问实例`_中所示。

2. 在 ServiceNow 中创建一个应用程序注册表，并使用它来配置连接器。

   1. 登录 ServiceNow 实例，然后选择 Homepage。

   2. 搜索 OAuth，然后选择 Application Registry。

   3. 依次选择 New、Create an OAuth API endpoint for external clients。

      系统会显示应用程序注册表的配置页，如下图所示：

      

   4. 在 ServiceNow 中的字段 Name 中，输入 OAuth 应用程序注册表的名称。

   5. 在 ServiceNow 的 Redirect URL field 中，输入以下内容：

      https://apps-api.c1.<cloud_region_id>.<cloud>.app.snowflake.cn/oauth/complete-secret
      

      Copy

      其中：

      cloud_region_id

      指定 Snowflake 账户的云区域的标识符。

      cloud

      指定云平台的标识符（例如 aws、azure 或 gcp）。

   6. 如果需要，请在 ServiceNow 中更新字段 Refresh Token Lifespan 和 Access Token Lifespan 的值。

      • Snowflake 建议将访问令牌的有效期设置为至少 600 秒。

      • 对于刷新令牌的有效期，请指定值为 7776000（90 天）。

   7. 在 ServiceNow 中，选择 Submit。

      OAuth 应用程序注册表显示在应用程序注册表列表中。

   8. 在 ServiceNow 中，选择您刚刚创建的应用程序注册表。

      请注意， ServiceNow 为字段 Client ID 和 Client Secret 生成了值。在下一节中，您可以在 创建安全集成 时使用这些值。

生成 OAuth 刷新令牌¶

要生成 OAuth 刷新令牌，请执行以下步骤：

1. 确保您已执行 设置 OAuth 中概述的任务。

2. 向 ServiceNow 实例的 /oauth_token.do 端点发送 HTTP 请求，如 ServiceNow 文档中的 REST OAuth 示例 (https://docs.servicenow.com/bundle/washingtondc-api-reference/page/integrate/inbound-rest/reference/r_RESTOAuthExample.html) 所述。

   例如，如果您使用 curl 发送 HTTP 请求：

   curl -d "grant_type=password" --data-urlencode "client_id=<client_id>" --data-urlencode "client_secret=<client_secret>" --data-urlencode "username=<username>" --data-urlencode "password=<password>" -X POST https://<instance_name>.service-now.com/oauth_token.do
   

   Copy

   其中

   instance_name

   指定 ServiceNow 实例的名称。

   client_id 和 client_secret

   指定设置 ServiceNow 端点时获取的值。

   username 和 password

   为 ServiceNow 实例指定凭证。

   备注

   上面的示例使用 curl 中的 data-urlencode 命令行标志对发送到 ServiceNow 的 HTTP 请求中的客户端密钥、用户名和密码进行 URL 编码 (link removed)。

   如果使用其他工具发送 HTTP 请求，请确保对请求中的这些值进行 URL 编码。

   HTTP 响应的正文包含一个 JSON 对象。从以下对象的 refresh_token 字段获取刷新令牌：

   {"access_token":"abcd1234","refresh_token":"cdef567","scope":"useraccount","token_type":"Bearer","expires_in":1799}
   

   Copy

创建安全集成¶

安全集成是一个 Snowflake 对象，它在 Snowflake 和第三方 OAuth 2.0 服务之间提供一个接口。

使用命令 CREATE SECURITY INTEGRATION 创建安全集成，如以下示例所示：

CREATE SECURITY INTEGRATION <name>
 TYPE = API_AUTHENTICATION
 AUTH_TYPE = OAUTH2
 OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
 OAUTH_CLIENT_ID = '<client_id>'
 OAUTH_CLIENT_SECRET = '<client_secret>'
 OAUTH_TOKEN_ENDPOINT = 'https://<my_instance>.service-now.com/oauth_token.do'
 ENABLED = TRUE;

其中：

name

指定安全集成的名称。

client_id

指定在上一节中从 ServiceNow 获取的 Client ID 字段的值。

client_secret

指定在上一节中从 ServiceNow 获取的 Client Secret 字段的值。

my_instance

指定 ServiceNow 实例的名称。这是您的 ServiceNow 实例主机名的第一部分。例如，如果指向您的 ServiceNow 实例的 URL 为：

https://myinstance.service-now.com

Copy

实例的名称将是 myinstance。

创建密钥对象¶

创建 Snowflake Connector for ServiceNow® 用于身份验证的 Snowflake 密钥对象。

Snowflake 建议使用专用角色来管理密钥对象，该角色要与 ACCOUNTADMIN 角色（用于安装、配置和运行连接器）区分开。Snowflake 还建议将密钥对象存储在专用数据库和架构中。请注意，您可以选择任意角色来管理密钥，也可以选择任意数据库和架构来存储密钥。

若要创建自定义角色来管理密钥，请使用以下 CREATE ROLE 命令。有关可以授予角色的权限的信息，请参阅 访问控制权限。

下一节介绍如何创建存储在单独的数据库和架构中并由自定义角色管理的密钥对象。

创建仓库¶

Snowflake 建议 创建一个连接器专用仓库。专用仓库可以更好地进行成本管理和资源跟踪。为了便于资源跟踪，您可以选择为专用仓库 添加一个或多个标签。

对于连接器仓库，Snowflake 建议使用大型多集群仓库。

若要创建名为 servicenow_conn_warehouse 的大型仓库，请运行以下命令：

USE ROLE accountadmin;
CREATE WAREHOUSE servicenow_conn_warehouse WAREHOUSE_SIZE = LARGE;

Copy

创建用于 ServiceNow 数据的数据库和架构¶

接下来，创建用于 ServiceNow 数据的数据库和架构。Snowflake Connector for ServiceNow® 将 ServiceNow 数据引入到此数据库和架构中。

创建数据库和架构时，请注意以下事项：

• 架构和数据库的名称必须是有效的 对象标识符。

• 要控制对 Snowflake 中引入的 ServiceNow 数据的访问，您可以 将架构的权限授予应可以访问数据的角色。

若要创建数据库和架构，请运行 CREATE DATABASE 和 CREATE SCHEMA 命令。

例如，若要为 ServiceNow 数据创建数据库 dest_db 和架构 dest_schema，请运行以下命令：

USE ROLE accountadmin;
CREATE DATABASE dest_db;
CREATE SCHEMA dest_schema;

Copy

创建 API 集成，用于与 ServiceNow 实例通信¶

接下来，创建一个 API 集成，用于与 ServiceNow 实例通信。使用以下语法运行命令 CREATE API INTEGRATION：

CREATE API INTEGRATION <integration_name>
  API_ALLOWED_PREFIXES = ('https://<servicenow_instance_name>.service-now.com')
  ALLOWED_AUTHENTICATION_SECRETS = (<secret_name>)
  ENABLED = TRUE

Copy

其中：

integration_name

指定 API 集成的名称。该名称必须是有效的 对象标识符。该名称在您账户中的 API 集成中必须是唯一的。

API_ALLOWED_PREFIXES = ('https://servicenow_instance_name.service-now.com')

指定您的 ServiceNow 实例的 URL。这将限制该 API 集成的使用范围，仅限于使用指定 URL 的实例。

ALLOWED_AUTHENTICATION_SECRETS = (secret_name)

指定允许在 API 集成范围内使用的密钥名称的列表。

将此值设置为您在 创建密钥对象 中创建的密钥对象的名称。

ENABLED = TRUE

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

TRUE

允许集成基于集成定义中指定的参数运行。

FALSE

暂停集成以进行维护。Snowflake 与第三方服务之间的任何集成都无法正常工作。

例如，要为名为 myinstance 的 ServiceNow 实例创建名为 servicenow_api_integration 的 API 集成，请运行以下命令：

USE ROLE accountadmin;
CREATE API INTEGRATION servicenow_api_integration
  API_ALLOWED_PREFIXES = ('https://myinstance.service-now.com')
  ALLOWED_AUTHENTICATION_SECRETS = (secretsdb.apiauth.servicenow_creds_pw)
  ENABLED = TRUE

Copy

为连接器配置日志记录¶

Snowflake Connector for ServiceNow® 使用事件表来存储连接器的错误日志。要设置事件表，请遵循 设置事件表 指南。如果未设置事件表，则系统会丢弃日志和事件信息。

为连接器创建自定义角色¶

接下来，为连接器创建自定义角色，并将运行连接器所需的权限授予该角色。

此角色允许连接器执行以下操作：

• 创建和管理数据引入任务。

• 使用专用仓库。

• 访问密钥和 API 集成以连接到 ServiceNow 实例。

该角色同时也是包含由连接器引入 ServiceNow 数据的表和视图的所有者。

要创建此角色并授予权限，请执行以下操作：

1. 使用 USERADMIN 系统角色运行命令 CREATE ROLE，创建自定义角色以拥有数据。例如，创建一个自定义角色 connector_resources_provider，以便拥有相关数据，请运行以下命令：

   USE ROLE useradmin;
   CREATE ROLE connector_resources_provider;
   

   Copy

2. 使用该 ACCOUNTADMIN 角色，运行 GRANT <privileges> to ROLE 命令，以向自定义角色授予以下权限：

   • 账户的 EXECUTE TASK 权限

   • 以下其中一项，但不能同时授予两项：

     • EXECUTE MANAGED TASK

       如果配置了没有专用仓库的连接器，则授予此权限。

     • 为连接器创建的 仓库的 USAGE 权限。

       如果为连接器使用专用仓库，则授予此权限。

   • 为 ServiceNow 数据创建的数据库 的 USAGE 权限

   • 为 ServiceNow 数据创建的架构 <label-servicenow_connector_prereqs_dest_schema>` 的 USAGE、CREATE TABLE 和 CREATE VIEW :ref:` 权限

   • 为 ServiceNow 创建的 API 集成 的 USAGE 权限

   • 为密钥创建的数据库的 USAGE 权限

   • 为密钥创建的架构的 USAGE 权限

   • 创建的密钥 的 USAGE 权限

   例如，要向名为 connector_resources_provider 的角色授予以下权限：

   • 账户的 EXECUTE TASK 权限

   • 账户的 EXECUTE MANAGED TASK 权限

   • 仓库 servicenow_conn_warehouse 的 USAGE 权限

   • dest_db 数据库的 USAGE 权限

   • 架构 dest_db.dest_schema 的 USAGE、CREATE TABLE 和 CREATE VIEW 权限

   • 集成 servicenow_api_integration 的 USAGE 权限

   • secretsdb 数据库的 USAGE 权限

   • 架构 secretsdb.apiauth 的 USAGE 权限

   • 密钥 secretsdb.apiauth.servicenow_creds_oauth_code secret 的 USAGE 权限

   请运行以下命令：

   USE ROLE accountadmin;
   
   GRANT EXECUTE TASK ON ACCOUNT TO ROLE connector_resources_provider;
   GRANT EXECUTE MANAGED TASK ON ACCOUNT TO ROLE connector_resources_provider;
   
   GRANT USAGE ON WAREHOUSE servicenow_conn_warehouse TO ROLE connector_resources_provider;
   
   GRANT USAGE ON DATABASE dest_db TO ROLE connector_resources_provider;
   GRANT USAGE ON SCHEMA dest_db.dest_schema TO ROLE connector_resources_provider;
   GRANT CREATE TABLE ON SCHEMA dest_db.dest_schema TO ROLE connector_resources_provider;
   GRANT CREATE VIEW ON SCHEMA dest_db.dest_schema TO ROLE connector_resources_provider;
   
   GRANT USAGE ON INTEGRATION servicenow_api_integration TO ROLE connector_resources_provider;
   
   GRANT USAGE ON DATABASE secretsdb TO ROLE connector_resources_provider;
   GRANT USAGE ON SCHEMA secretsdb.apiauth TO ROLE connector_resources_provider;
   GRANT USAGE ON SECRET secretsdb.apiauth.servicenow_creds_oauth_code TO ROLE connector_resources_provider;
   

   Copy

安装 Snowflake Connector for ServiceNow® 后，将此角色授予连接器。

虽然建议在开始引入后创建单独的、更细化的角色来访问引入的数据，但您可以用此角色来查询引入的数据，还可以用额外的权限进行扩展。反之，不允许撤销连接器所需的对象的角色权限，亦不允许更改具有引入数据的表和视图的角色所有权，否则会破坏连接器。

安装 Snowflake Connector for ServiceNow®¶

要安装连接器，请执行以下操作：

1. 使用 Snowsight 为连接器实例创建数据库。有关如何创建数据库的详细信息，请参阅 使用 Snowsight 安装和配置连接器。

2. 导航到 SQL 工作表。

3. 以具有 ACCOUNTADMIN 角色的用户身份登录。例如：

   USE ROLE ACCOUNTADMIN;
   

   Copy

4. 将连接器的自定义角色（ 您之前创建的角色）授予 用作连接器实例的数据库。

   例如，要为名为 connector_resources_provider 的角色授予数据库 my_connector_servicenow，请运行以下命令：

   GRANT ROLE connector_resources_provider TO DATABASE my_connector_servicenow;
   

   Copy

5. 运行命令 USE DATABASE 以将数据库用于连接器。例如：

   USE DATABASE my_connector_servicenow;
   

   Copy

6. 使用 CALL 命令配置与 ServiceNow 实例的连接，以调用名为 CONFIGURE_CONNECTION 的存储过程：

   CALL CONFIGURE_CONNECTION({
      'serviceNowUrl': '<servicenow_base_url>',
      'secret': '<secret_name>',
      'apiIntegrationName': '<api_integration_name>'
   })
   

   Copy

   其中：

   servicenow_base_url

   指定连接器应使用的 ServiceNow 实例的 URL。URL 应采用以下格式：

   https://<servicenow_instance_name>.service-now.com
   

   Copy

   secret_name

   指定包含 ServiceNow 身份验证凭据的 密钥（您之前创建的密钥）对象 的完全限定名称。

   您必须按以下格式指定密钥对象的完称：

   <database_name>.<schema_name>.<secret_name>
   

   Copy

   数据库、架构和密钥的名称必须是有效的 对象标识符。

   api_integration_name

   指定 ServiceNow API 集成的名称（您之前创建的 API 集成）。

   集成的名称必须是有效的 对象标识符。

   例如，要配置与 ServiceNow 实例的连接，请执行以下操作：

   • 包含 URL https://myinstance.service-now.com。

   • 使用存储在 secretsdb.apiauth.servicenow_creds_oauth_code 中的密钥。

   • 使用名为 servicenow_api_integration 的 API 集成。

   运行以下命令：

    CALL CONFIGURE_CONNECTION({
       'serviceNowUrl': 'https://myinstance.service-now.com',
       'secret': 'SECRETSDB.APIAUTH.SERVICENOW_CREDS_OAUTH_CODE',
       'apiIntegrationName': 'SERVICENOW_API_INTEGRATION'
   });
   

   Copy

   如果连接配置成功，则此存储过程将打印以下消息：

   Connection configured successfully
   

   Copy

   备注

   配置连接器后，无法更改传递的密钥和 API 集成的名称。因为连接器通过名称来引用它们。因此，如果尝试删除或修改这些对象的名称，将会导致连接器失效并停止正常工作。

7. 按照 启动 Snowflake Connector for ServiceNow® 中所述启动连接器。

新创建的数据库是连接器实例，包含以下内容：

• 用于配置连接器的存储过程。有关更多信息，请参阅 使用 SQL 语句设置数据引入。

• 包含连接器记录的消息和统计信息的视图。有关更多信息，请参阅 关于监控连接器。

启动和停止 Snowflake Connector for ServiceNow®¶

以下各节介绍如何启动、停止和恢复连接器。

CALL START_CONNECTOR(
  '<warehouse_name>',
  '<dest_db_schema>',
  '<name_of_journal_table>',
  '<connector_role>'
);

Successfully started the |SNC|. The connector can be configured now.

CALL RESUME_CONNECTOR();

委派用于配置和监控 Snowflake Connector for ServiceNow® 的权限¶

安装连接器后，只有 ACCOUNTADMIN 角色才能运行配置过程并访问用于监控连接器的视图。

若要将这些权限委派给其他角色，请运行命令 GRANT IMPORTED PRIVILEGES ON DATABASE ... TO ROLE ...。此命令使用以下语法：

GRANT IMPORTED PRIVILEGES ON DATABASE <connector_name> TO ROLE <connector_config_role>;

其中：

connector_name

指定 用作连接器实例的数据库的名称。

connector_config_role

指定应被授予连接器配置和监控权限的角色的名称。

例如，要创建名为 connector_config_role 的自定义角色，并授予该角色配置和监控名为 my_connector_servicenow 的连接器实例的权限，请运行以下命令：

USE ROLE useradmin;
CREATE ROLE connector_config_role;

USE ROLE securityadmin;
GRANT IMPORTED PRIVILEGES ON DATABASE my_connector_servicenow TO ROLE connector_config_role;

更改连接器使用的仓库（可选）¶

如果要更改连接器使用的仓库或添加专用仓库，请通过调用以下命令执行此操作：

CALL CONFIGURE_WAREHOUSE('<warehouse_name>');

Copy

其中：

warehouse_name

指定连接器应使用的仓库的名称。

要将连接器配置为在不使用专用仓库的情况下运行，请为仓库名称传递空字符串。

后续步骤¶

安装并配置连接器后，执行“ 为 ServiceNow® 数据设置数据引入”中描述的步骤。