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

Instalação do Snowflake Connector for ServiceNow®V2¶

O seguinte procedimento descreve como instalar o conector:

1. Entre em Snowsight como um usuário com a função ACCOUNTADMIN.

2. No menu de navegação, selecione Data Products » Marketplace.

3. Procure o Snowflake Connector for ServiceNow®V2, depois selecione o bloco para o conector.

4. Na página do Snowflake Connector for ServiceNow®V2, selecione Get.

   Isto exibe uma caixa de diálogo que você utiliza para iniciar a parte inicial do processo de instalação.

   Na caixa de diálogo, configure o seguinte:

   1. No campo Application name, insira o nome do banco de dados a ser usado como banco de dados para a instância do conector. Este banco de dados é criado automaticamente para você.

   2. No campo Warehouse used for installation, selecione o warehouse que você deseja usar para a instalação do conector.

      Nota

      Este não é o mesmo warehouse que é usado pelo conector para sincronizar os dados do ServiceNow®. Em uma etapa posterior, você criará um warehouse separado para este fim.

   3. Selecione Get.

5. Uma caixa de diálogo aparece com a notificação: Installing App After installation, an email will be sent to <e-mail do usuário>. Para prosseguir com a configuração usando SQL, feche a caixa de diálogo e vá para Worksheets.

Configuração de OAuth¶

Você pode configurar o Snowflake Connector for ServiceNow®V2 para usar o OAuth e 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®V2:

  • 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 ServiceNow® OAuth, 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®V2 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ê quiser usar essa instância com o Snowflake Connector for ServiceNow®V2, anote o ID do cliente, o segredo do cliente e o 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 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 conforme 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® e 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. 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).

   6. No ServiceNow, selecione Submit.

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

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

Criação de objetos essenciais¶

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;

USE ROLE accountadmin;
CREATE WAREHOUSE servicenow_conn_warehouse WAREHOUSE_SIZE = LARGE;

SHOW PARAMETERS LIKE 'STATEMENT_TIMEOUT_IN_SECONDS' FOR ACCOUNT;
SHOW PARAMETERS LIKE 'STATEMENT_TIMEOUT_IN_SECONDS' FOR WAREHOUSE <connector_warehouse>;

ALTER ACCOUNT SET STATEMENT_TIMEOUT_IN_SECONDS = 10800;
ALTER WAREHOUSE <connector_warehouse> SET STATEMENT_TIMEOUT_IN_SECONDS = 10800;

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

CREATE NETWORK RULE <name>
  MODE = 'EGRESS'
  TYPE = 'HOST_PORT'
  VALUE_LIST = ('<servicenow_instance_name>.service-now.com');

USE ROLE secretadmin;
GRANT USAGE ON SECRET secretsdb.apiauth.<secret_name> TO ROLE ACCOUNTADMIN;

CREATE EXTERNAL ACCESS INTEGRATION <integration_name>
  ALLOWED_NETWORK_RULES = (<network_rule_name>)
  ALLOWED_AUTHENTICATION_SECRETS = (<secret_name>)
  ENABLED = TRUE;

Configuração do registro em log do conector¶

O Snowflake Connector for ServiceNow®V2 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.

Configuração do conector instalado¶

Para configurar 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 todos os privilégios necessários ao conector no banco de dados que serve como uma instância do conector.

   • EXECUTE TASK na conta

   • EXECUTE MANAGED TASK na conta

   • USAGE no warehouse que você criou para o segredo.

   • 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 o dados do ServiceNow®

   • USAGE sobre a integração de acesso externo 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

   • READ no segredo que você criou

   Por exemplo, para conceder os seguintes privilégios ao conector nomeado my_connector_servicenow:

   • 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_external_access_integration

   • USAGE no banco de dados secretsdb

   • USAGE no esquema secretsdb.apiauth

   • READ no segredo secretsdb.apiauth.servicenow_creds_oauth_code secret

   Execute os seguintes comandos:

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

   Copy

5. Transferência da propriedade de tabelas e exibições no esquema de destino (opcional)

   Se o conector foi reinstalado e o esquema de destino anterior foi reutilizado, a propriedade de todas as tabelas e exibições no esquema de destino deve ser transferida ao conector. O conector requer privilégio de propriedade para gerenciar concessões em objetos no esquema e recriar exibições niveladas quando o esquema da tabela ingerida for alterado.

   Para transferir a chamada de propriedade, chame a função SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION.

   USE ROLE accountadmin;
   CALL SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION(<connector_app>, true, <destination_database>, <destination_schema>);
   

   Copy

   SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION é uma função de sistema fornecida pelo Snowflake que permite a transferência de propriedade de tabelas e exibições em um banco de dados ou esquema especificado para o aplicativo. Somente a propriedade de tabelas regulares e exibições comuns é transferida; a propriedade de tabelas dinâmicas, tabelas externas e exibições materializadas, por exemplo, não será transferida.

   A função possui a seguinte assinatura:

   SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION(<to_app>, <should_copy_grants>, <from_database>, <from_schema>)
   

   Copy

   Onde:

   to_app

   Especifica o nome do aplicativo para o qual a propriedade dos objetos deve ser transferida.

   should_copy_grants

   Se TRUE, então copie as concessões existentes, caso contrário, revogue. A cópia de subsídios requer a permissão MANAGE GRANTS no chamador.

   from_database

   Nome do banco de dados que contém objetos cuja propriedade deve ser alterada.

   from_schema

   Nome do esquema que contém objetos cuja propriedade deve ser alterada (opcional). Se nenhum esquema for especificado, a propriedade será transferida em tabelas exibições em todos os esquemas no banco de dados fornecido. Objetos em esquemas gerenciados são omitidos durante a transferência de propriedade.

   Para executar a função, o chamador deve atender a uma das seguintes condições:

   • Ter a permissão MANAGE GRANTS (por exemplo, função ACCOUNTADMIN ou SECURITYADMIN); ou

   • Conter a função proprietária da instância do aplicativo e a função proprietária de todos os objetos para transferir a propriedade. Os objetos cuja propriedade está ausente são omitidos pela função.

   Por exemplo, para transferir a propriedade do conector que:

   • Foi instalado como o aplicativo nomeado my_connector_servicenow

   • Usa o esquema nomeado dest_db.dest_schema para os dados do ServiceNow® no Snowflake

   Execute o seguinte comando:

   USE ROLE accountadmin;
   CALL SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION('my_connector_servicenow', true, 'dest_db', 'dest_schema');
   

   Copy

   Se necessário, conceda a função de aplicativo DATA_READER para a função que anteriormente possuía os dados para evitar interrupções de pipelines existentes que usam os dados:

   GRANT APPLICATION ROLE <connector_app>.DATA_READER TO ROLE <previous_data_owner_role>;
   

   Copy

   Observe que a função de aplicativo DATA_READER não terá nenhuma concessão em tabelas e exibições no esquema de destino até que o procedimento CONFIGURE_CONNECTOR seja executado.

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 o conector usando o comando CALL para chamar o procedimento armazenado nomeado CONFIGURE_CONNECTOR:

   CALL CONFIGURE_CONNECTOR({
     'warehouse': '<warehouse_name>',
     'destination_database': '<dest_db>',
     'destination_schema': '<dest_schema>'
   })
   

   Copy

   Onde:

   warehouse_name

   Especifica o nome do warehouse para o conector.

   O nome do warehouse deve ser um identificador de objeto válido.

   dest_db

   Especifica o nome do banco de dados para os dados ServiceNow® no Snowflake (o banco de dados que você criou anteriormente).

   O nome do banco de dados deve ser identificadores de objeto válidos.

   dest_schema

   Especifica o nome do esquema para os dados ServiceNow® no Snowflake (o esquema que você criou anteriormente).

   O nome do esquema deve ser um identificador de objeto válido.

   Por exemplo, para configurar o conector que:

   • Utiliza o warehouse servicenow_conn_warehouse.

   • Usa o esquema nomeado dest_db.dest_schema para os dados do ServiceNow® no Snowflake

   Execute o seguinte comando:

   CALL CONFIGURE_CONNECTOR({
     'warehouse': 'servicenow_conn_warehouse',
     'destination_database': 'dest_db',
     'destination_schema': 'dest_schema'
   });
   

   Copy

   Se o conector foi iniciado com sucesso, este procedimento armazenado retorna a seguinte resposta:

   {
     "responseCode": "OK",
     "message": "Connector successfully configured.",
   }
   

   Copy

   Nota

   Depois que o conector for iniciado, não será possível renomear o warehouse passado, o banco de dados de destino e o esquema de destino do conector. 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.

   Em vez de renomear o warehouse, use o procedimento armazenado UPDATE_WAREHOUSE para alterar o warehouse usado pelo conector.

8. Configure a conexão para a instância do ServiceNow® usando o comando CALL para chamar o procedimento armazenado nomeado SET_CONNECTION_CONFIGURATION:

   CALL SET_CONNECTION_CONFIGURATION({
     'service_now_url': '<servicenow_base_url>',
     'secret': '<secret_name>',
     'external_access_integration': '<external_access_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.

   external_access_integration_name

   Especifica o nome da integração de acesso externo para o ServiceNow® (a integração de acesso externo 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.

   • Utiliza a integração de acesso externo nomeada servicenow_external_access_integration.

   Execute o seguinte comando:

   CALL SET_CONNECTION_CONFIGURATION({
     'service_now_url': 'https://myinstance.service-now.com',
     'secret': 'SECRETSDB.APIAUTH.SERVICENOW_CREDS_OAUTH_CODE',
     'external_access_integration': 'SERVICENOW_API_INTEGRATION'
   });
   

   Copy

   Se a conexão foi configurada com sucesso, este procedimento armazenado retorna a seguinte resposta:

   {
     "responseCode": "OK",
     "message": "Test request to ServiceNow® succeeded.",
   }
   

   Copy

   Nota

   Depois que a conexão estiver configurada, não será possível alterar o nome do segredo passado e da integração de acesso externo. 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.

9. Finalize a configuração do conector usando o comando CALL para chamar o procedimento armazenado nomeado FINALIZE_CONNECTOR_CONFIGURATION:

   CALL FINALIZE_CONNECTOR_CONFIGURATION({
     'journal_table': '<name_of_journal_table>',
     'table_name': '<name_of_audited_table>',
     'sys_id': '<sys_id_of_audited_entry>'
   })
   

   Copy

   Onde:

   name_of_journal_table

   Especifica o nome da tabela que contém informações sobre os registros excluídos. Para obter mais informações, consulte Preparação de sua instância do ServiceNow®.

   Observe que as informações sobre os registros excluídos estão disponíveis apenas para as tabelas que você configura para propagar os registros excluídos.

   Para evitar a propagação de registros excluídos, especifique um valor null para este argumento.

   name_of_audited_table

   Especifica o nome da tabela auditada que deve estar presente na tabela de diário e à qual o conector deve ter acesso (opcional). Durante a validação do acesso à tabela de diário, o conector procura entradas de auditoria relacionadas a esta tabela. Forneça esta opção quando uma consulta para o ServiceNow® for bem-sucedida, mas não der resultado, fazendo com que o procedimento falhe. Assegurar que o usuário do ServiceNow® para o conector tem acesso a todas as entradas da tabela especificada.

   Esta opção não pode ser usada com o parâmetro sys_id.

   sys_id_of_audited_entry

   Especifica o sys_id de entrada de alguma tabela auditada que deve estar presente na tabela de diário e à qual o conector deve ter acesso (opcional). Durante a validação do acesso à tabela de diário, o conector procura entradas de auditoria relacionadas a esta sys_id. Forneça esta opção quando uma consulta para o ServiceNow® for bem-sucedida, mas não der resultado, fazendo com que o procedimento falhe. Certifique-se de que o usuário do ServiceNow® para o conector tenha acesso à entrada especificada.

   Esta opção não pode ser usada com o parâmetro table_name.

   Se o conector foi iniciado com sucesso, este procedimento armazenado retorna a seguinte resposta:

   {
       "responseCode": "OK",
   }
   

   Copy

   Durante a finalização da configuração do conector, o conector tentará verificar se um estado do conector exportado anteriormente está presente no esquema de destino. Se a tabela __CONNECTOR_STATE_EXPORT estiver presente e acessível ao conector, o conector tentará importar o estado. Quando a importação for concluída com sucesso, a tabela de exportação será excluída. Se ocorrer um erro durante a importação, é possível executar o procedimento FINALIZE_CONNECTOR_CONFIGURATION novamente após corrigir o erro. Se você não quiser importar o estado ou não quiser corrigir o erro de importação, transfira a propriedade da tabela do conector e descarte a tabela.

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.

Funções do aplicativo do conector¶

Como um aplicativo nativo, o Snowflake Connector for ServiceNow®V2 define funções de aplicativo. Eles podem ser revisados em Controle de acesso baseado em funções para conectores.

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®.