Install and configure the connector with SQL commands

Este tópico descreve como usar os comandos SQL para instalar e configurar o conector. Ele considera que você já tenha realizado os procedimentos descritos em Prepare your ServiceNow® instance.

Install the Snowflake Connector for ServiceNow®

O seguinte procedimento descreve como instalar o conector:

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

  2. In the navigation menu, select Marketplace » Snowflake Marketplace.

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

  4. Na página do Snowflake Connector for ServiceNow®, 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>. Agora você pode fechar a caixa de diálogo. Para continuar a configuração usando SQL, aguarde até receber um e-mail informando que o 'Snowflake Connector para ServiceNow' está instalado e pronto para uso e, em seguida, acesse Worksheets.

Set up OAuth

Nota

Se você planeja usar autenticação básica em vez de OAuth, você pode pular esta seção e continuar em Create a secret object

Você pode configurar o Snowflake Connector for ServiceNow® para usar o OAuth para autenticação na instância do ServiceNow®. Há dois fluxos do OAuth compatíveis:

  • Concessão de credenciais do cliente (recomendado): Disponível desde a versão Washington DC. As credenciais do cliente são um padrão de autorização amplamente aceito para integração entre máquinas e não exigem manutenção de tokens com atualização manual.

  • Fluxo de concessão de código de autorização: Esse método de autenticação está disponível em todas as versões do ServiceNow compatíveis, mas com este método os tokens do OAuth devem ser atualizados manualmente antes da data de expiração, normalmente a cada 3 meses.

Set up OAuth with client credentials grant flow

Para configurar o Snowflake Connector for ServiceNow® para usar o OAuth com o fluxo de concessão de credenciais do cliente para autenticação na instância do ServiceNow®, faça o seguinte:

  • No ServiceNow®, você deve configurar a instância usando o OAuth com o fluxo de concessão de credenciais do cliente.

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

      Quando o OAuth é usado para autenticar, o conector armazena o escopo do OAuth do ServiceNow® e o nome da integração de segurança no objeto do segredo do Snowflake.

Se sua instância do ServiceNow® já usar o fluxo de concessão de credenciais do cliente do OAuth e você quiser usar essa instância com o Snowflake Connector for ServiceNow®, 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 essas informações, prossiga para criar objetos essenciais

Configure ServiceNow® instance to use the OAuth with client credentials grant flow

  1. Configure sua instância para usar o OAuth com o fluxo de concessão do código de autorização, conforme mostrado em Configurar OAuth.

  2. Crie um ponto de extremidade para que os clientes acessem a instância e use-o para configurar o conector:

    1. Faça login em sua instância do ServiceNow® e selecione Homepage.

    2. Procure sys_properties.list.

    3. Procure a propriedade com o nome glide.oauth.inbound.client.credential.grant_type.enabled na tabela e certifique-se de que ela esteja definida como true.

      Nota

      Se a propriedade não existir, crie-a. Clique no botão New e preencha os seguintes campos da nova propriedade:

      • Defina Name como glide.oauth.inbound.client.credential.grant_type.enabled,

      • Defina Type como true | false,

      • Defina Value como true.

    4. Procure o System OAuth, depois selecione Application Registry.

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

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

    7. No ServiceNow®, selecione o usuário com que você quer que o conector seja autenticado no campo OAuth Application User. O usuário precisa ter os privilégios listados em Prepare your ServiceNow® instance.

      Nota

      Se o campo OAuth Application User não estiver disponível no formulário, abra o menu Additional actions no canto superior esquerdo da tela. Selecione o menu Configure > Form builder. Em seguida, adicione o campo OAuth Application User que está faltando na exibição Default formulário. Save o formulário e atualize a página para continuar.

    8. No ServiceNow®, selecione Submit.

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

    9. 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ê usará esses valores quando criar uma integração de segurança.

Set up OAuth with authorization code grant flow

Para configurar o Snowflake Connector for ServiceNow® para usar o OAuth com fluxo de concessão de código de autorização para autenticação na instância do ServiceNow®:

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

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

Se sua instância do ServiceNow® já usar o fluxo de concessão de código de autorização do OAuth e você quiser usar essa instância com o Snowflake Connector for ServiceNow®, 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 essas informações, prossiga para gerar o token de atualização do OAuth

Configure ServiceNow® instance to use the OAuth with authorization code grant flow

  1. Configure sua instância para usar o OAuth com o fluxo de concessão do código de autorização, conforme mostrado em Configurar OAuth.

  2. Crie um ponto de extremidade para que os clientes acessem a instância 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:

      Exibe a página do registro do aplicativo em ServiceNow®.

    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ê usará esses valores quando criar uma integração de segurança.

Generate OAuth refresh token

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

  1. Envie uma solicitação HTTP para o ponto de extremidade /oauth_token.do de sua instância do ServiceNow®, conforme 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://<servicenow_instance>.service-now.com/oauth_token.do

    Onde

    <servicenow_instance>

    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 ao 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}

Create essential objects

Create a security integration (optional)

Nota

Se você planeja usar autenticação básica em vez de OAuth, você pode pular esta seção e continuar em Create a secret object

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.

Create a security integration for OAuth with client credentials grant flow

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://<servicenow_instance>.service-now.com/oauth_token.do'
 OAUTH_GRANT = 'CLIENT_CREDENTIALS'
 OAUTH_ALLOWED_SCOPES = ('useraccount')
 ENABLED = TRUE;

Onde:

name

Especifica o nome da integração de segurança. O nome deve ser obrigatoriamente único entre as integrações na sua conta.

client_id

Especifica o valor do campo Client ID que você obteve ao configurar o ponto de extremidade do ServiceNow®.

client_secret

Especifica o valor do campo Client Secret que você obteve ao configurar o ponto de extremidade do ServiceNow®.

servicenow_instance_name

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

https://myinstance.service-now.com

O nome de sua instância seria myinstance.

Create a security integration for OAuth with authorization code grant flow

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://<servicenow_instance>.service-now.com/oauth_token.do'
 ENABLED = TRUE;

Onde:

name

Especifica o nome da integração de segurança. O nome deve ser obrigatoriamente único entre as integrações na sua conta.

client_id

Especifica o valor do campo Client ID que você obteve ao configurar o ponto de extremidade do ServiceNow®.

client_secret

Especifica o valor do campo Client Secret que você obteve ao configurar o ponto de extremidade do ServiceNow®.

servicenow_instance_name

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

https://myinstance.service-now.com

O nome de sua instância seria myinstance.

Create a secret object

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

Snowflake recomenda o armazenamento do objeto secreto em um banco de dados e esquema dedicados. 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 gerenciar o segredo, use o comando CREATE ROLE. Para obter 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.

Create a schema for the secret objects

Primeiro, crie um banco de dados e um esquema para armazenar o objeto secreto executando os comandos CREATE DATABASE e CREATE SCHEMA. Os nomes do esquema e do banco de dados devem ser identificadores de objeto.

Por exemplo, para criar o banco de dados secretsdb e o esquema apiauth para o objeto secreto, execute os seguintes comandos:

USE ROLE accountadmin;
CREATE DATABASE secretsdb;
CREATE SCHEMA apiauth;

Create a custom role to manage the secret (optional)

Em seguida, crie uma função personalizada para administrar o segredo (assumindo que você não queira usar uma função existente) e conceda à função os privilégios necessários para criar o segredo.

  1. Usando a função USERADMIN do sistema, execute o comando CREATE ROLE para criar uma função personalizada para gerenciar o segredo. Por exemplo, para criar a função personalizada secretadmin para gerenciar o segredo, execute os seguintes comandos:

    USE ROLE useradmin;
CREATE ROLE secretadmin;

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

    Por exemplo:

    USE ROLE securityadmin;
GRANT USAGE ON DATABASE secretsdb TO ROLE secretadmin;
GRANT USAGE ON SCHEMA secretsdb.apiauth TO role secretadmin;
GRANT CREATE SECRET ON SCHEMA secretsdb.apiauth TO role secretadmin;

  3. (opcional) Se estiver configurando o conector com a autenticação OAuth, conceda também o privilégio USAGE na integração de segurança que você criou anteriormente para a função personalizada.

    Por exemplo:

    USE ROLE securityadmin;
GRANT USAGE ON INTEGRATION servicenow_oauth TO role secretadmin;

  4. Usando a função USERADMIN do sistema, execute o comando GRANT <privilégios> … TO ROLE para conceder a função personalizada ao usuário que cria o segredo. Por exemplo, para conceder a função ao usuário servicenow_secret_owner, execute os seguintes comandos:

    USE ROLE useradmin;
GRANT ROLE secretadmin TO user servicenow_secret_owner;

Create a secret

Em seguida, crie um segredo para permitir que o Snowflake se autentique na instância do ServiceNow® usando OAuth com o fluxo de concessão do código de autorização.

Nota

Se você planeja usar autenticação básica em vez de OAuth, consulte a nota abaixo em vez disso.

Para criar um objeto secreto para o fluxo de concessão de credenciais do cliente do OAuth, execute o comando CREATE SECRET com os seguintes parâmetros:

  • Defina TYPE como OAUTH2.

  • Defina API_AUTHENTICATION como o nome da integração de segurança que você criou em Create essential objects:

  • Defina OAUTH_SCOPES como useraccount.

Por exemplo, para criar um segredo chamado service_now_creds_oauth_code que usa a integração de segurança chamada servicenow_oauth, execute estes comandos:

USE ROLE secretadmin;
USE SCHEMA secretsdb.apiauth;
CREATE SECRET servicenow_creds_oauth_code
  TYPE = OAUTH2
  API_AUTHENTICATION = servicenow_oauth
  OAUTH_SCOPES=('useraccount');

Para criar um objeto secreto para o fluxo de concessão de código de autorização do OAuth, execute o comando CREATE SECRET com os seguintes parâmetros:

  • Defina TYPE como OAUTH2.

  • Defina OAUTH_REFRESH_TOKEN como o token de atualização do OAuth que você recuperou em Generate OAuth refresh token.

  • Defina OAUTH_REFRESH_TOKEN_EXPIRY_TIME como o carimbo de data/hora da expiração do token de atualização no fuso horário UTC. Você pode calcular isto adicionando a vida útil do token do ServiceNow® até a data em que o token foi emitido. Por padrão, o token expira em 100 dias.

  • Defina API_AUTHENTICATION como o nome da integração de segurança que você criou em Create essential objects:

Por exemplo, para criar um segredo chamado service_now_creds_oauth_code que usa a integração de segurança chamada servicenow_oauth, execute estes comandos:

USE ROLE secretadmin;
USE SCHEMA secretsdb.apiauth;
CREATE SECRET servicenow_creds_oauth_code
  TYPE = OAUTH2
  OAUTH_REFRESH_TOKEN = 'cdef567'
  OAUTH_REFRESH_TOKEN_EXPIRY_TIME = '2022-01-06 20:00:00'
  API_AUTHENTICATION = servicenow_oauth;

Para modificar as propriedades de um segredo existente (por exemplo, para atualizar o token de atualização do OAuth), use o comando ALTER SECRET.

Nota

Se você planeja usar a autenticação básica (em vez de OAuth), execute o comando CREATE SECRET para criar um segredo com TYPE definido como PASSWORD. Defina USERNAME e PASSWORD como o nome de usuário e senha do usuário do ServiceNow® que você pretende usar para autenticar na instância do ServiceNow®. Por exemplo:

USE ROLE secretadmin;
USE SCHEMA secretsdb.apiauth;
CREATE SECRET servicenow_creds_pw
  TYPE = PASSWORD
  USERNAME = 'jsmith1'
  PASSWORD = 'W3dr@fg*7B1c4j';

Se a autenticação multifator estiver habilitada para este usuário, você deve fornecer o token MFA junto com a senha, conforme descrito em REST API na documentação do ServiceNow®.

Create a 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 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;

Atenção

Certifique-se de que o warehouse seja capaz de executar uma consulta por pelo menos 8 horas. Ele é afetado por um valor de parâmetro que pode ser definido tanto no warehouse usado pelo conector quanto na conta (o valor da conta tem precedência). Para verificar os valores atuais, execute:

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

Se ambos os valores forem pelo menos 28800 (ou seja, 8 horas), então nenhuma alteração é necessária. Caso contrário, execute um dos seguintes procedimentos, conforme necessário:

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

Se o tempo limite adequado não for fornecido, ocorrerão falhas na ingestão de dados.

Create a database and schema for the ServiceNow® data

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:

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;

Nota

Se você estiver reinstalando o conector, você pode reutilizar o esquema que criou para a instalação anterior do conector. Isto é possível se a instalação anterior do conector já tiver carregado dados e você quiser continuar carregando dados nas mesmas tabelas.

Para continuar carregando dados, não modifique o esquema antes de reinstalar o conector. Não altere as definições das tabelas criadas pela instalação anterior do conector.

O conector exporta periodicamente a configuração e o estado do conector para uma tabela __CONNECTOR_STATE_EXPORT no esquema, que pode ser usada posteriormente para recuperar a configuração do conector durante a reinstalação. Alternativamente, se a tabela de exportação não estiver presente ou foi descartada manualmente, você ainda pode chamar o procedimento armazenado ENABLE_TABLES para reativar as tabelas ingeridas anteriormente. O procedimento armazenado verifica se todos os objetos necessários já existem e não tenta recriá-los, portanto não há risco de perder dados já ingeridos.

Create a network rule for communicating with the ServiceNow® instance

Em seguida, para permitir o tráfego de saída de sua conta para sua instância do ServiceNow®, crie uma regra de rede. Como administrador de conta, execute o comando CREATE NETWORK RULE com a seguinte sintaxe:

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

Onde:

name

Especifica o nome da regra de rede. O nome deve ser um identificador de objeto válido.

VALUE_LIST = ('servicenow_instance_name.service-now.com')

Especifica a lista de instâncias do ServiceNow® permitidas às quais uma solicitação pode ser enviada.

Por exemplo, para criar a regra de rede chamada servicenow_network_rule dentro do esquema apiauth do banco de dados secretsdb, execute o seguinte comando:

USE ROLE accountadmin;
CREATE NETWORK RULE secretsdb.apiauth.servicenow_network_rule
  MODE = 'EGRESS'
  TYPE = 'HOST_PORT'
  VALUE_LIST = ('myinstance.service-now.com');

Nota

Se você criou o segredo com uma função personalizada, você precisa conceder adicionalmente o privilégio USAGE sobre ele para ACCOUNTADMIN antes de criar a regra de rede:

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

Create an external access integration for communicating with the ServiceNow® instance

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

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

Onde:

integration_name

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

ALLOWED_NETWORK_RULES = (network_rule_name)

Especifica a regra de rede que permite o acesso à sua instância do ServiceNow®. Isto limita o uso desta integração às instâncias com as URLs especificados na regra de rede.

Defina isto como o nome da regra de rede que você criou em Create a network rule for communicating with the ServiceNow® instance.

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 Create a secret object.

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 acesso externo nomeada servicenow_external_access_integration, execute o seguinte comando:

USE ROLE accountadmin;
CREATE EXTERNAL ACCESS INTEGRATION servicenow_external_access_integration
  ALLOWED_NETWORK_RULES = (secretsdb.apiauth.servicenow_network_rule)
  ALLOWED_AUTHENTICATION_SECRETS = (secretsdb.apiauth.servicenow_creds_pw)
  ENABLED = TRUE

Configure logging for the connector

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.

Importante

O Snowflake recomenda que você configure o rastreamento de eventos para ajudar a solucionar problemas.

Set up the installed connector

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;

  4. Conceda todos os privilégios necessários ao conector no banco de dados que serve como uma instância do conector.

    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;

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

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

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

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

    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;

  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>'
})

    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 identificadores de objeto válidos.

    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'
});

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

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

    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>'
})

    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>.service-now.com
    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>

    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'
});

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

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

    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 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>'
})

    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 Prepare your ServiceNow® instance.

    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",
}

    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:

Funções do aplicativo do conector

Como um aplicativo nativo, o Snowflake Connector for ServiceNow® define funções de aplicativo. Eles podem ser revisados em Role-based access control for connectors (ServiceNow).

Exemplos de scripts de instalação

Os exemplos de scripts a seguir demonstram como configurar o Snowflake Connector for ServiceNow® usando planilhas SQL. Isso pode ajudar você a configurar rapidamente e começar a usar o conector em seu ambiente. Basta copiar e colar os comandos na planilha e preencher os espaços reservados com seus valores.

Importante

Supõe-se que o aplicativo já está instalado na conta, conforme descrito aqui.

Antes de executar os comandos, revise o script e ajuste-o às suas necessidades:

-- Specify values as required by your installation
SET application_name = 'SNOWFLAKE_CONNECTOR_FOR_SERVICENOW'; -- use the same name as provided in the installation
SET connector_warehouse = 'SNOWFLAKE_CONNECTOR_FOR_SERVICENOW_WAREHOUSE';
SET servicenow_instance_domain = '<servicenow_instance>.service-now.com';

SET destination_database = 'SNOWFLAKE_CONNECTOR_FOR_SERVICENOW_DEST_DB';
SET destination_schema = 'SNOWFLAKE_CONNECTOR_FOR_SERVICENOW_DEST_SCHEMA';

SET secret_database = 'CONNECTORS_SECRET';
SET secret_schema = 'SNOWFLAKE_CONNECTOR_FOR_SERVICENOW';
SET secret_database_schema = $secret_database || '.' || $secret_schema;
SET secret_fqn = $secret_database_schema || '.' || 'SECRET';

SET network_rule_fqn = $secret_database_schema || '.' || 'NETWORK_RULE';
SET external_access_integration_name = 'SNOWFLAKE_CONNECTOR_FOR_SERVICENOW_EXTERNAL_ACCESS_INTEGRATION';

SET destination_database_schema = $destination_database || '.' || $destination_schema;
SET servicenow_instance_url = 'https://' || $servicenow_instance_domain || '/';

-- Create essential objects
USE ROLE accountadmin;

CREATE WAREHOUSE IF NOT EXISTS IDENTIFIER($connector_warehouse)
   WAREHOUSE_SIZE = 'MEDIUM'
   AUTO_RESUME = TRUE;
CREATE DATABASE IF NOT EXISTS IDENTIFIER($secret_database);
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($secret_database_schema);
CREATE DATABASE IF NOT EXISTS IDENTIFIER($destination_database);
CREATE SCHEMA IF NOT EXISTS IDENTIFIER($destination_database_schema);

-- Populate with your credentials
CREATE SECRET IDENTIFIER($secret_fqn)
   TYPE = PASSWORD
   USERNAME = '<servicenow_login>'
   PASSWORD = '<servicenow_password>';

-- None of the following commands should require any changes
CREATE NETWORK RULE IDENTIFIER($network_rule_fqn)
   MODE = 'EGRESS'
   TYPE = 'HOST_PORT'
   VALUE_LIST = ($servicenow_instance_domain);

CREATE PROCEDURE execute_immediate_create_ea_integration()
RETURNS VARIANT
EXECUTE AS caller
AS
BEGIN
   EXECUTE IMMEDIATE '
      CREATE EXTERNAL ACCESS INTEGRATION IDENTIFIER($external_access_integration_name)
      ALLOWED_NETWORK_RULES = ($network_rule_fqn)
      ALLOWED_AUTHENTICATION_SECRETS = ('  ||  $secret_fqn  ||  ') ENABLED = TRUE
   ';
END;
CALL execute_immediate_create_ea_integration();
DROP PROCEDURE IF EXISTS execute_immediate_create_ea_integration();

GRANT EXECUTE TASK ON ACCOUNT TO APPLICATION IDENTIFIER($application_name);
GRANT EXECUTE MANAGED TASK ON ACCOUNT TO APPLICATION IDENTIFIER($application_name);

GRANT USAGE ON WAREHOUSE IDENTIFIER($connector_warehouse) TO APPLICATION IDENTIFIER($application_name);
GRANT USAGE ON DATABASE IDENTIFIER($destination_database) TO APPLICATION IDENTIFIER($application_name);
GRANT USAGE ON SCHEMA IDENTIFIER($destination_database_schema) TO APPLICATION IDENTIFIER($application_name);

GRANT CREATE TABLE ON SCHEMA IDENTIFIER($destination_database_schema) TO APPLICATION IDENTIFIER($application_name);
GRANT CREATE VIEW ON SCHEMA IDENTIFIER($destination_database_schema) TO APPLICATION IDENTIFIER($application_name);

GRANT USAGE ON INTEGRATION IDENTIFIER($external_access_integration_name) TO APPLICATION IDENTIFIER($application_name);
GRANT USAGE ON DATABASE IDENTIFIER($secret_database) TO APPLICATION IDENTIFIER($application_name);
GRANT USAGE ON SCHEMA IDENTIFIER($secret_database_schema) TO APPLICATION IDENTIFIER($application_name);
GRANT READ ON SECRET IDENTIFIER($secret_fqn) TO APPLICATION IDENTIFIER($application_name);

CALL SYSTEM$GRANT_OWNERSHIP_TO_APPLICATION($application_name, true, $destination_database, $destination_schema);

USE APPLICATION IDENTIFIER($application_name);

-- Recommended to call one by one as the response might contain an error
CALL CONFIGURE_CONNECTOR({
   'warehouse': $connector_warehouse,
   'destination_database': $destination_database,
   'destination_schema': $destination_schema
});

CALL SET_CONNECTION_CONFIGURATION({
   'service_now_url': $servicenow_instance_url,
   'secret': $secret_fqn,
   'external_access_integration': $external_access_integration_name
});

-- Remove the 'journal_table' parameter if you don't want to track deleted records
CALL FINALIZE_CONNECTOR_CONFIGURATION({
   'journal_table': 'sys_audit_delete'
});

Próximos passos

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