Instalação e configuração do conector usando comandos SQL¶

Configuração do OAuth¶

Você pode configurar o Snowflake Connector for ServiceNow® para usar OAuth para autenticar na instância do ServiceNow:

• No ServiceNow, você deve configurar a instância para suporte usando OAuth com o fluxo de concessão de código.

• No Snowflake Connector for ServiceNow®:

  • O conector usa uma integração de segurança com TYPE = API_AUTHENTICATION para conectar o Snowflake à instância do ServiceNow.

    A integração de segurança especifica o ID do cliente do OAuth ServiceNow, o segredo do cliente e a URL do ponto de extremidade para autenticar na instância do ServiceNow.

  • O conector usa um objeto secreto Snowflake para gerenciar informações sensíveis, incluindo as credenciais de autenticação.

    No caso de usar OAuth para autenticação, o conector armazena o token de atualização do ServiceNow OAuth, o tempo de validade do token de expiração e o nome da integração de segurança no objeto secreto Snowflake.

Para configurar o Snowflake Connector for ServiceNow® para usar OAuth, siga estes passos:

1. Configure sua instância do ServiceNow para usar o OAuth com o fluxo de concessão de código.

   • Se sua instância do ServiceNow já usar o fluxo de concessão de código do OAuth e você gostaria de usar essa instância com o Snowflake Connector for ServiceNow®, anote o ID do cliente, segredo do cliente e URL do ponto de extremidade que corresponde ao token de OAuth.

     Para obter mais informações, consulte Gerenciamento de tokens do OAuth. Depois de anotar estas informações, crie uma integração de segurança na próxima etapa.

   • Se você quiser usar uma instância diferente do ServiceNow, acesse ou crie a instância e configure a instância para usar OAuth com o fluxo de concessão de código como mostrado em Configuração de OAuth e Criação de um ponto de extremidade para clientes para acessar a instância.

2. Crie um registro do aplicativo no ServiceNow e use-o para configurar o conector.

   1. Faça o login em sua instância do ServiceNow, depois selecione Homepage.

   2. Procure o OAuth, depois selecione Application Registry.

   3. Selecione New e depois selecione Create an OAuth API endpoint for external clients.

      Isto exibe uma página de configuração para o registro do aplicativo, como mostrado na imagem a seguir:

      

   4. No ServiceNow, digite um nome para o registro do aplicativo do OAuth no campo Name.

   5. No ServiceNow, em Redirect URL field, digite o seguinte:

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

      Copy

      Onde:

      cloud_region_id

      Especifica o identificador da região da nuvem de sua conta Snowflake.

      cloud

      Especifica o identificador da plataforma de nuvem (por exemplo, aws, azure ou gcp).

   6. Se necessário, no ServiceNow, atualize os valores nos campos Refresh Token Lifespan e Access Token Lifespan.

      • Snowflake recomenda ajustar a vida útil do token de acesso para pelo menos 600 segundos.

      • Para a vida útil do token de atualização, especifique um valor que seja 7776000 (90 dias).

   7. No ServiceNow, selecione Submit.

      O registro do aplicativo do OAuth aparece na lista de registros do aplicativo.

   8. No ServiceNow, selecione o registro do aplicativo que você acabou de criar.

      Observe que o ServiceNow gerou valores para os campos Client ID e Client Secret. Você usa estes valores na próxima seção quando cria uma integração de segurança.

Como gerar o token de atualização do OAuth¶

Para gerar o token de atualização do OAuth:

1. Certifique-se de ter realizado as tarefas descritas em Configuração do OAuth.

2. Envie uma solicitação HTTP para o ponto de extremidade /oauth_token.do de sua instância do ServiceNow, como explicado no exemplo do REST OAuth na documentação do ServiceNow.

   Por exemplo, se você estiver usando curl para enviar a solicitação 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

   Onde

   instance_name

   Especifica o nome de sua instância do ServiceNow.

   client_id e client_secret

   Especifique os valores obtidos ao configurar o ponto de extremidade do ServiceNow.

   username e password

   Especifique as credenciais para sua instância do ServiceNow.

   Nota

   O exemplo acima usa o sinalizador data-urlencode de linha de comando em curl para codificação do URL do segredo do cliente, nome de usuário e senha na solicitação HTTP enviada para o ServiceNow.

   Se você estiver usando uma ferramenta diferente para enviar a solicitação HTTP, certifique-se de que você faça a codificação URL destes valores na solicitação.

   O corpo da resposta HTTP contém um objeto JSON. Obtenha o token de atualização do campo refresh_token neste objeto:

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

   Copy

Criação de uma integração de segurança¶

Uma integração de segurança é um objeto Snowflake que fornece uma interface entre o Snowflake e um serviço de OAuth 2.0 de terceiros.

Use o comando CREATE SECURITY INTEGRATION para criar uma integração de segurança, como mostrado no exemplo a seguir:

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;

Onde:

name

Especifica o nome da integração de segurança.

client_id

Especifica o valor do campo Client ID que você obteve do ServiceNow na seção anterior.

client_secret

Especifica o valor do campo Client Secret que você obteve do ServiceNow na seção anterior.

my_instance

Especifica o nome de sua instância do ServiceNow. Esta é a primeira parte do nome do host de sua instância do ServiceNow. Por exemplo, se o URL para sua instância do ServiceNow for:

https://myinstance.service-now.com

Copy

O nome de sua instância seria myinstance.

Criação de um objeto secreto¶

Crie o objeto secreto Snowflake que o Snowflake Connector for ServiceNow® usa para autenticação.

Snowflake recomenda o uso de uma função dedicada para gerenciar o objeto secreto, separada da função ACCOUNTADMIN (a função que você usa para instalar, configurar e executar o conector). Snowflake também recomenda o armazenamento do objeto secreto em um banco de dados e esquema dedicado. Observe que você pode escolher qualquer função para administrar o segredo, e pode escolher qualquer banco de dados e esquema para armazenar o segredo.

Para criar uma função personalizada para administrar o segredo, use o comando CREATE ROLE. Para obter mais informações sobre os privilégios que você pode conceder a uma função, consulte Privilégios de controle de acesso.

As próximas seções explicam como criar um objeto secreto que seja armazenado em um banco de dados e esquema separado e que seja gerenciado por uma função personalizada.

Como criar um warehouse¶

Snowflake recomenda a criação de um warehouse dedicado ao conector. Um warehouse dedicado permite uma melhor gestão de custos e rastreamento de recursos. Para facilitar o rastreamento de recursos, você pode opcionalmente adicionar uma ou mais tags ao warehouse dedicado.

Para o warehouse do conector, a Snowflake recomenda o uso de um warehouse multicluster de grande porte.

Para criar um warehouse de grande porte chamado servicenow_conn_warehouse, execute o seguinte comando:

USE ROLE accountadmin;
CREATE WAREHOUSE servicenow_conn_warehouse WAREHOUSE_SIZE = LARGE;

Copy

Criação de um banco de dados e esquema para os dados do ServiceNow¶

Em seguida, crie um banco de dados e um esquema para os dados do ServiceNow. O Snowflake Connector for ServiceNow® faz a ingestão dos dados do ServiceNow no banco de dados e esquema.

Ao criar o banco de dados e o esquema, observe o seguinte:

• Os nomes do esquema e do banco de dados devem ser identificadores de objeto válidos.

• Para controlar o acesso aos dados ingeridos do ServiceNow no Snowflake, você pode conceder os privilégios no esquema às funções que devem ser permitidas para acessar os dados.

Para criar o banco de dados e o esquema, execute os comandos CREATE DATABASE e CREATE SCHEMA.

Por exemplo, para criar o banco de dados dest_db e o esquema dest_schema para os dados do ServiceNow, execute os seguintes comandos:

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

Copy

Criação de uma integração de API para a comunicação com a instância do ServiceNow¶

Em seguida, crie uma integração de API para a comunicação com a instância do ServiceNow. Execute o comando CREATE API INTEGRATION com a seguinte sintaxe:

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

Copy

Onde:

integration_name

Especifica o nome da integração de API. O nome deve ser um identificador de objeto válido. O nome deve ser obrigatoriamente único entre as integrações de API em sua conta.

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

Especifica o URL para sua instância do ServiceNow. Isto limita o uso desta integração de API à instância com o URL especificado.

ALLOWED_AUTHENTICATION_SECRETS = (secret_name)

Especifica a lista dos nomes dos segredos que são permitidos para uso no escopo da integração de API.

Defina isto como o nome do objeto secreto que você criou em Criação de um objeto secreto.

ENABLED = TRUE

Especifica se esta integração de API está habilitada ou desabilitada. Se a integração de API estiver desativada, qualquer função externa que conte com ela não funcionará.

TRUE

Permite que a integração funcione com base nos parâmetros especificados na definição da integração.

FALSE

Suspende a integração para manutenção. Qualquer integração entre o Snowflake e um serviço de terceiro não funciona.

Por exemplo, para criar a integração de API denominada servicenow_api_integration para a instância do ServiceNow denominada myinstance, execute o seguinte comando:

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

Configuração do registro do conector¶

O Snowflake Connector for ServiceNow® usa tabelas de eventos para armazenar logs de erros do conector. Para configurar uma tabela de eventos, siga o guia Configuração de uma tabela de eventos. Se a tabela de eventos não estiver configurada, as informações de log e eventos serão descartadas.

Criação de uma função personalizada para o conector¶

Em seguida, crie uma função personalizado para o conector, e conceda os privilégios necessários para executar o conector.

Esta função permite que o conector o faça o seguinte:

• Crie e gerencie tarefas para ingerir os dados.

• Use o warehouse dedicado.

• Acesse o segredo e a integração de API a fim de conectar-se à instância do ServiceNow.

A função também é a proprietária das tabelas e exibições que contêm os dados do ServiceNow ingeridos pelo conector.

Para criar esta função e conceder os privilégios:

1. Usando a função USERADMIN do sistema, execute o comando CREATE ROLE para criar uma função personalizada para ser proprietária dos dados. Por exemplo, para criar a função personalizada connector_resources_provider para ser proprietária dos dados, execute os seguintes comandos:

   USE ROLE useradmin;
   CREATE ROLE connector_resources_provider;
   

   Copy

2. Usando a função ACCOUNTADMIN, execute o comando GRANT <privilégios> para ROLE para conceder os seguintes privilégios à função personalizada:

   • EXECUTE TASK na conta

   • Uma das seguintes opções, mas não ambas:

     • EXECUTE MANAGED TASK

       Conceda este privilégio se você tiver configurado o conector sem um warehouse dedicado.

     • USAGE no warehouse que você criou para o segredo

       Conceda este privilégio se você estiver usando um warehouse dedicado para o conector.

   • USAGE no banco de dados que você criou para os dados do ServiceNow.

   • USAGE, CREATE TABLE e CREATE VIEW no esquema que você criou para os dados do ServiceNow

   • USAGE na integração de API que você criou para o ServiceNow

   • USAGE no banco de dados que você criou para o segredo

   • USAGE no esquema que você criou para o segredo

   • USAGE no segredo que você criou

   Por exemplo, para conceder os seguintes privilégios à função chamada connector_resources_provider:

   • EXECUTE TASK na conta

   • EXECUTE MANAGED TASK na conta

   • USAGE no warehouse servicenow_conn_warehouse

   • USAGE no banco de dados dest_db

   • USAGE, CREATE TABLE e CREATE VIEW no esquema dest_db.dest_schema

   • USAGE na integração servicenow_api_integration

   • USAGE no banco de dados secretsdb

   • USAGE no esquema secretsdb.apiauth

   • USAGE no segredo secretsdb.apiauth.servicenow_creds_oauth_code secret

   Execute os seguintes comandos:

   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

Depois de instalar o Snowflake Connector for ServiceNow®, você concede esta função ao conector.

Embora seja recomendado criar funções separadas e mais refinadas para acessar dados ingeridos após o início da ingestão, você pode usar essa função para consultar dados ingeridos e estendê-los com privilégios adicionais. Por outro lado, a revogação de privilégios de função para objetos exigidos pelo conector ou alterações na propriedade de funções de tabelas e exibições com dados ingeridos não é permitida e interromperá o conector.

Instalação do Snowflake Connector for ServiceNow®¶

Para instalar o conector:

1. Crie um banco de dados para a instância do conector usando o Snowsight. Para obter mais informações sobre como criar o banco de dados, consulte Instalação e configuração do conector com Snowsight.

2. Navegue até a planilha SQL.

3. Entrar como um usuário com a função ACCOUNTADMIN. Por exemplo:

   USE ROLE ACCOUNTADMIN;
   

   Copy

4. Conceda a função personalizada para o conector (a função que você criou anteriormente) ao banco de dados que serve como uma instância do conector.

   Por exemplo, para conceder a função chamada connector_resources_provider ao banco de dados my_connector_servicenow, execute o seguinte comando:

   GRANT ROLE connector_resources_provider TO DATABASE my_connector_servicenow;
   

   Copy

5. Defina a propriedade FIREWALL_CONFIGURATION do banco de dados no banco de dados instalado. Inclua o prefixo do URL para sua instância do ServiceNow.

   Por exemplo, se seu banco de dados for nomeado my_connector_servicenow e o nome da instância do ServiceNow for my-instance, execute o seguinte comando:

   ALTER DATABASE my_connector_servicenow SET FIREWALL_CONFIGURATION = ('https://my-instance.service-now.com')
   

   Copy

6. Execute o comando USE DATABASE para usar o banco de dados para o conector. Por exemplo:

   USE DATABASE my_connector_servicenow;
   

   Copy

7. Configure a conexão para a instância do ServiceNow usando o comando CALL para chamar o procedimento armazenado chamado CONFIGURE_CONNECTION:

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

   Copy

   Onde:

   servicenow_base_url

   Especifica o URL da instância do ServiceNow que o conector deve usar. O URL deve estar no seguinte formato:

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

   Copy

   secret_name

   Especifica o nome totalmente qualificado do objeto secreto contendo as credenciais para autenticação no ServiceNow (o segredo que você criou anteriormente).

   Você deve especificar o nome totalmente qualificado do objeto secreto no seguinte formato:

   <database_name>.<schema_name>.<secret_name>
   

   Copy

   Os nomes do banco de dados, do esquema e do segredo devem ser identificadores de objeto válidos.

   api_integration_name

   Especifica o nome da integração da API como ServiceNow (a integração da API que você criou anteriormente).

   O nome da integração deve ser um identificador de objeto válido.

   Por exemplo, para configurar a conexão a uma instância do ServiceNow que:

   • Tenha o URL https://myinstance.service-now.com.

   • Utilize o segredo armazenado em secretsdb.apiauth.servicenow_creds_oauth_code.

   • Utilize a integração de API denominada servicenow_api_integration.

   Execute o seguinte comando:

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

   Copy

   Se a conexão foi configurada com sucesso, este procedimento armazenado imprimirá a seguinte mensagem:

   Connection configured successfully
   

   Copy

   Nota

   Depois que o conector estiver configurado, não será possível alterar o nome do segredo passado e da integração de API. O conector faz referência a eles por nome. Como resultado, uma tentativa de descartar ou alterar o nome desses objetos quebrará o conector e impedirá seu funcionamento.

8. Inicie o conector como descrito em Início do Snowflake Connector for ServiceNow®.

O banco de dados recém-criado é uma instância do conector e contém o seguinte:

• Procedimentos armazenados que você usa para configurar o conector. Consulte Configuração da ingestão de dados usando instruções SQL para obter mais informações.

• Exibições contendo as mensagens registradas e estatísticas para o conector. Consulte Sobre o monitoramento do conector para obter mais informações.

Como iniciar e parar o Snowflake Connector for ServiceNow®¶

As seções a seguir descrevem como iniciar, parar e retomar o conector.

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();

Delegação de privilégios para configuração e monitoramento do Snowflake Connector for ServiceNow®¶

Após instalar o conector, somente a função ACCOUNTADMIN poderá executar os procedimentos de configuração e acessar as exibições usadas para monitorar o conector.

Para delegar estes privilégios a outra função, execute o comando GRANT IMPORTED PRIVILEGES ON DATABASE ... TO ROLE .... Este comando usa a seguinte sintaxe:

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

Onde:

connector_name

Especifica o nome do banco de dados que serve como instância do conector.

connector_config_role

Especifica o nome da função que deve receber os privilégios para configurar e monitorar o conector.

Por exemplo, para criar uma função personalizada chamada connector_config_role e conceder a essa função os privilégios de configurar e monitorar a instância do conector chamada my_connector_servicenow, execute o seguinte comando:

USE ROLE useradmin;
CREATE ROLE connector_config_role;

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

Mudança do warehouse utilizado pelo conector (opcional)¶

Se você quiser mudar o warehouse usado pelo conector ou adicionar um warehouse dedicado, faça isso chamando:

CALL CONFIGURE_WAREHOUSE('<warehouse_name>');

Copy

Onde:

warehouse_name

Especifica o nome do warehouse que o conector deve usar.

Para configurar o conector para funcionar sem utilizar um warehouse dedicado, passe em uma cadeia de caracteres vazia para o nome do warehouse.

Próximos passos¶

Após instalar e configurar o conector, execute as etapas descritas em Configuração da ingestão de dados para seus dados do ServiceNow®.