Consulte os conectores compatíveis com o Application Integration.

Tarefa do Conectores

A tarefa Conectores permite que você se conecte com facilidade aos vários serviços do Google Cloud e a outros aplicativos de negócios da sua integração usando os conectores prontos para uso disponíveis em Conectores de integração

Para ver a lista de todos os conectores compatíveis com o Application Integration, consulte Referência de conectores.

Importante: os conectores de integração são um componente faturável do Google Cloud. Para informações sobre os custos e as cobranças de uso dos conectores de integração, consulte os preços dos conectores de integração.

Antes de começar

• Verifique se você tem o papel do IAM de Administrador do Connectors (roles/connectors.admin) no projeto do Google Cloud. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
• Saiba mais sobre os conceitos gerais dos Integration Connectors.
• Para se conectar aos serviços do Google Cloud e a outros aplicativos comerciais usando um conector, verifique se você anexou uma conta de serviço gerenciada pelo usuário à integração. Se a integração não tiver uma conta de serviço gerenciada pelo usuário configurada, a conta de serviço padrão ([e-mail]) será usada para autenticação por padrão.
• Verifique se a conta de serviço tem o papel do IAM necessário. Para informações sobre como conceder papéis a uma conta de serviço, consulte Gerenciar o acesso a contas de serviço.

Adicionar uma tarefa do Connectors

Para adicionar a tarefa "Conectores" à sua integração, faça o seguinte:

1. No console do Google Cloud, acesse a página Application Integration.

   Acessar o Application Integration

2. No menu de navegação, clique em Integrações.

   A página Integrações aparece listando todas as integrações disponíveis no projeto do Google Cloud.

3. Selecione uma integração ou clique em Criar integração para criar uma nova.

   Caso você esteja criando uma nova integração, siga estas etapas:

   1. Insira um nome e uma descrição no painel Criar integração.
   2. Selecione uma região para a integração.
      Observação: o menu suspenso Regiões lista apenas as regiões provisionadas no projeto do Google Cloud. Para provisionar uma nova região, clique em Ativar região. Consulte Ativar nova região para obter mais informações.
   3. Selecione uma conta de serviço para a integração. Você pode mudar ou atualizar os detalhes da conta de serviço de uma integração a qualquer momento no painel Resumo da integração na barra de ferramentas da integração.
      Observação:a opção de selecionar uma conta de serviço só vai aparecer se você tiver ativado a governança de integração para a região selecionada.
   4. Clique em Criar.

   Isso abre a integração na página do editor de integração.

4. Na barra de navegação do editor de integração, clique em Tarefas para conferir a lista de opções disponíveis.
5. Clique e coloque o elemento Conectores no editor de integração.

Configurar a tarefa do Conectores

Para configurar uma tarefa de conectores, faça o seguinte:

Observação: Os detalhes de configuração, como a autenticação, variam de acordo com o tipo de conexão.

1. Clique no elemento de tarefa dos Conectores no designer para ver o painel de configuração da tarefa dos Conectores.

   Também é possível clicar no para editar o nome da tarefa.

2. Clique em Configurar conector.
3. É possível selecionar uma conexão existente na região ou criar uma nova. Para configurar uma conexão existente, siga as etapas a seguir na página Editor de tarefas de conectores:
1. Em Selecionar conectores, selecione a região da conexão.
2. Escolha uma conexão existente na lista de conexões disponíveis na região selecionada.
3. Clique em Próxima.
4. Na lista Tipo, selecione Entidades ou Ações.
   • Se você selecionar Entidades, a lista de entidades compatíveis com a conexão será exibida na seção Definir entidades/ações. Selecione uma entidade seguida pela operação que será executada nela.
   • Se você selecionar Ações, a lista de ações compatíveis com a conexão será exibida na coluna Definir entidades/ações. Selecione uma ação para a conexão.
   As entidades e ações compatíveis são baseadas no tipo de conector. Para ver a lista de todos os conectores compatíveis com o Application Integration, consulte Referência de conectores. Para ver as ações e entidades compatíveis com um conector, consulte a documentação específica.

   Se o conector for compatível com a consulta SQL personalizada, será possível selecionar a opção Executar consulta personalizada na lista Ações. Para informações sobre como adicionar uma consulta SQL personalizada para seu conector, consulte Ação: executar consulta SQL personalizada.

   Observação: nem todos os tipos de conexão são compatíveis com entidades e ações. Se um tipo de conexão não for compatível com nenhuma ação ou entidade, as listas Entidades e Ações correspondentes ficarão vazias. Para saber mais sobre entidades e ações, consulte Entidades, operações e ações.
5. Clique em Concluído para concluir a configuração da conexão e feche o painel.

A imagem a seguir mostra um layout de amostra da página Editor de tarefas dos conectores.

Configurar variáveis de entrada e saída da tarefa

O painel de configuração de tarefas dos Conectores exibe as variáveis Entrada de tarefas e Saída de tarefas, que são geradas automaticamente com base na entidade e operação ou na ação selecionada na caixa de diálogo Configurar conector da tarefa. Essas variáveis podem ser configuradas e acessadas como entradas para a tarefa atual ou saídas para tarefas seguintes ou condicionais configuradas na integração atual.

Para configurar as variáveis Entrada de tarefa ou Saída de tarefa, clique na variável correspondente para abrir o painel Configurar variável e execute as seguintes etapas:

1. Insira o valor da variável no campo Valor padrão.
2. (Opcional) Selecione Usar como entrada para a integração ou Usar como saída para a integração.
3. Clique em Salvar.

Para mais informações sobre os parâmetros de entrada e saída da tarefa de conectores, consulte Operações de entidade.

Operações e ações de entidades

É possível executar operações CRUD (criar, ler, atualizar e excluir) nas entidades de um conector. Cada uma dessas operações de entidade tem um conjunto diferente de parâmetros de entrada e saída. A tabela a seguir descreve os parâmetros de entrada e saída das várias operações de entidade.

Nome da operação	Parâmetros de entrada	Parâmetros de saída
Lista	listEntitiesPageSize listEntitiesPageToken listEntitiesSortByColumns filterClause	connectorOutputPayload listEntitiesNextPageToken
Obter	entityId	connectorOutputPayload
	Observação: é possível usar a operação Get apenas para buscar um único registro de uma tabela que tenha uma chave primária. Como alternativa, é possível usar a operação List com uma filterClause.
Criar	connectorInputPayload	connectorOutputPayload
Atualizar	connectorInputPayload entityId filterClause	connectorOutputPayload
Excluir	entityId filterClause	N/A

Parâmetros de entrada

A tabela a seguir descreve os parâmetros de entrada para as várias operações de entidade.

Nome do parâmetro	Tipo de dados	Descrição
entityId	String	Um identificador exclusivo da linha que você quer acessar. Normalmente, entityId é um valor de chave primária de uma tabela ou um conjunto de dados. Se você especificar um valor para entityId, e a tabela ou o conjunto de dados não tiver uma coluna de chave primária, a integração informará um erro de ambiente de execução e a tarefa Conectores falhará. Por exemplo, para receber uma linha específica de uma tabela do MySQL, entityId é o valor da chave primária na tabela. Observação:o entityId não é obrigatório para o BigQuery. Este campo fica vazio quando uma tabela do BigQuery não tem uma chave primária.
connectorInputPayload	JSON	Os dados reais a serem adicionados ou atualizados em uma entidade. O exemplo a seguir mostra o snippet JSON de uma linha de dados a ser adicionada a uma tabela: { "employee_first_name": "John", "employee_emailID": "[e-mail]" } Neste exemplo, employee_first_name e employee_emailID são os nomes de colunas com os valores correspondentes John e [e-mail].
filterClause	String	Restringe o resultado das operações com base em uma condição. Para mais informações sobre como adicionar uma cláusula de filtro, consulte Adicionar um filtro para uma operação.
listEntitiesPageSize	Número inteiro	Especifica o número de resultados que precisam ser retornados em uma página. Uma página é um agrupamento lógico dos registros em um conjunto de resultados. O conceito de uma página é útil quando se espera um grande número de registros no conjunto de resultados. Se o conjunto de resultados for grande, a tarefa Connecters poderá falhar, já que há um limite no tamanho dos dados que a tarefa Connecters pode processar. Ao dividir o resultado em blocos menores, é possível evitar esse problema. Por exemplo, se você espera 1.000 registros no conjunto de resultados, defina listEntitiesPageSize como 100. Portanto, quando a tarefa Conectores for executada pela primeira vez, ela retornará os primeiros 100 registros, os próximos 100 registros na segunda execução e assim por diante. Importante: O tamanho padrão da página é 25, e o número máximo de páginas compatíveis com a tarefa é 50000. A menos que sua tabela ou conjunto de dados tenha uma chave primária, você precisará definir o parâmetro listEntitiesSortByColumns para usar listEntitiesPageToken. Use a injunção de parâmetros listEntitiesPageSize com o parâmetro listEntitiesPageToken para navegar pelas páginas.
listEntitiesPageToken	String	Um identificador de página (token) que permite acessar uma página específica. Consiga o valor de um token da página do parâmetro de saída listEntitiesNextPageToken. Como cada página tem um token exclusivo, você tem a flexibilidade de acessar qualquer página no conjunto de resultados. Para entender o uso desse parâmetro, leia também a descrição do parâmetro de saída listEntitiesNextPageToken.
listEntitiesSortByColumns	Matriz de strings	Nome da coluna pelo qual você quer classificar o conjunto de resultados. Observação: só é possível classificar o conjunto de resultados por uma coluna.

Parâmetros de saída

A tabela a seguir descreve os parâmetros de saída para as várias operações de entidade.

Nome do parâmetro	Tipo de dados	Descrição
connectorOutputPayload	JSON	A saída de uma operação no formato JSON.
listEntitiesNextPageToken	String	É um identificador gerado pelo sistema para uma página. Pense no token como um ponteiro pelo qual é possível acessar uma página específica do conjunto de resultados. Se você tiver dividido o conjunto de resultados em várias páginas definindo o parâmetro listEntitiesPageSize, será necessário um mecanismo para navegar pelas páginas. O parâmetro de saída listEntitiesNextPageToken permite fazer exatamente isso. Sempre que a tarefa Conectores é executada, o sistema gera um token para a próxima página e define o valor de listEntitiesNextPageToken como o token recém-gerado. Depois, use esse token para acessar a próxima página no conjunto de resultados. Para acessar a próxima página, defina o parâmetro de entrada listEntitiesPageToken como o valor do token da próxima página. Por exemplo, considere que você definiu o parâmetro listEntitiesPageSize como 2 e quando a tarefa Connectors é executada pela primeira vez, o listEntitiesNextPageToken é definido como o valor do token ChoKC2VtcGxveWVlX2lkEgkRAAAAAAAA8D8YDw==. Depois, é possível definir o parâmetro de entrada listEntitiesPageToken como esse valor de token para buscar a próxima página na próxima execução da tarefa Connectors. Se o conjunto de resultados tiver um grande número de páginas, considere usar a tarefa Para cada repetição para chamar repetidamente a tarefa Conectores e usar a tarefa Mapeamento de dados para atribuir automaticamente valores de token ao parâmetro de entrada listEntitiesPageToken após cada execução.

Cláusula de filtro para operações de entidade

É possível restringir os registros processados pela tarefa Conectores usando a variável Filtrar cláusula, disponível como uma Entrada de tarefas. Por exemplo, no caso de uma operação delete, é possível adicionar um filtro para excluir registros com um orderId específico.

A cláusula de filtro só pode ser aplicada às seguintes operações de entidade:

• Lista
• Excluir
• Atualizar

Ao selecionar qualquer uma dessas operações, a seção Entrada de tarefa da tarefa do Conectores mostra o campo Cláusula de filtro automaticamente.

Adicionar uma cláusula de filtro

Para adicionar um filtro, execute os seguintes passos:

1. Clique no elemento de tarefa dos Conectores no designer para ver o painel de configuração da tarefa dos Conectores.
2. Expanda a seção Entrada de tarefas e clique na variável de string filterCláusula(conectores).

   A caixa de diálogo "Configurar variável" será exibida.

3. Digite a cláusula de filtro (seguindo a sintaxe) no campo Valor padrão.
4. Clique em Salvar.

Filtrar sintaxe e exemplos de cláusula

Uma cláusula de filtro tem o seguinte formato:

FIELD_NAME CONDITION FILTER_VALUE

Exemplos

• OwnerId = '0053t000007941XAAQ'

• PoNumber < 2345

• OrderNumber = 00110 AND StatusCode = 'Draft'

• TotalAmount > 2500

• ShippingPostalCode = 94043 OR ShippingPostalCode = 77002

Observação: na cláusula de filtro, especifique os valores da string entre aspas simples ( ' ) ou duplas ( " ), dependendo do banco de dados. que você está usando. Por exemplo, o MySQL aceita aspas simples e duplas, enquanto o BigQuery aceita apenas aspas simples.

Uso de variáveis em uma cláusula de filtro

Não é possível usar uma variável de integração diretamente em uma cláusula de filtro. Se você quiser usar uma variável de integração, primeiro configure uma tarefa de mapeamento de dados para criar um mapeamento entre a variável e a cláusula de filtro.

A tabela a seguir mostra um mapeamento de exemplo entre uma variável de integração e a variável filterClause(Connectors):

Entrada	Saída
PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(')	filterClause(Connectors)

Em que PRIMARY_KEY_ID = ' é inserido como um Valor na linha de entrada.

---

Ação: executar consulta SQL personalizada

Para criar uma consulta salva, siga estas etapas:

1. Siga as instruções detalhadas para adicionar uma tarefa de conectores.
2. Quando você configurar a tarefa do conector, selecione Ações no tipo de ação que você quer realizar.
3. Na lista Ação, selecione Executar consulta personalizada e clique em Concluído.

   

4. Expanda a seção Entrada de tarefas e faça o seguinte:
   1. No campo Tempo limite após, digite o número de segundos de espera até que a consulta seja executada.

      Valor padrão: 180 segundos

   2. No campo Número máximo de linhas, digite o número máximo de linhas a serem retornadas do banco de dados.

      Valor padrão: 25.

   3. Para atualizar a consulta personalizada, clique em Editar script personalizado. A caixa de diálogo Editor de script é aberta.

      

   4. Na caixa de diálogo Editor de script, insira a consulta SQL e clique em Salvar.

      É possível usar um ponto de interrogação (?) em uma instrução SQL para representar um único parâmetro que precisa ser especificado na lista de parâmetros de consulta. Por exemplo, a seguinte consulta SQL seleciona todas as linhas da tabela Employees que correspondem aos valores especificados na coluna LastName:

      SELECT * FROM Employees where LastName=?

      Observação:há suporte para as instruções de linguagem de manipulação de dados (DML) e de linguagem de definição de dados (DDL).
   5. Se você usou pontos de interrogação na consulta SQL, adicione o parâmetro clicando em + Adicionar nome do parâmetro para cada ponto de interrogação. Ao executar a integração, esses parâmetros substituem os pontos de interrogação (?) na consulta SQL sequencialmente. Por exemplo, se você tiver adicionado três pontos de interrogação (?), deverá adicionar três parâmetros em ordem de sequência.

      

      Para adicionar parâmetros de consulta, faça o seguinte:

      1. Na lista Tipo, selecione o tipo de dados do parâmetro.
      2. No campo Valor, insira o valor do parâmetro.
      3. Para adicionar vários parâmetros, clique em + Adicionar parâmetro de consulta.

Atualização do esquema

Todas as entidades e ações terão um esquema associado a elas. Por exemplo, um esquema de ação terá os detalhes do parâmetro, como: os nomes do parâmetro e tipos de dados correspondentes. O esquema (metadados) de entidades e ações é buscado pela conexão no ambiente de execução do back-end. Se houver atualizações no esquema, elas não serão refletidas automaticamente nas suas conexões, faça isso manualmente. Para conferir o esquema atualizado nas tarefas do conector, siga estas etapas:

1. No Integration Connectors, abra a página Detalhes da conexão e clique em Atualizar esquema de conexão.
2. Na Application Integration, é preciso reconfigurar a tarefa do conector atual para a mesma conexão.

Criação de conexão inline

É possível usar a tarefa de conectores para criar uma conexão diretamente nos Integration Connectors.

Antes de começar

• Adicionar uma tarefa de conector

Criar nova conexão

Para criar uma nova conexão no Application Integration, siga estas etapas:

1. Clique no elemento de tarefa dos Conectores no designer para ver o painel de configuração da tarefa dos Conectores.
2. Clique em Configurar conector.

   A página Editor de tarefas de conectores é exibida.

3. Ignore o campo Região.
4. Clique em Conexão e selecione a opção Criar conexão no menu suspenso.
5. Conclua as etapas a seguir no painel Criar conexão:
   Observação: as instruções a seguir são genéricas para criar uma conexão. Embora a maioria das etapas permaneça a mesma para todos os tipos de conexão, pode haver variação em algumas etapas ou detalhes adicionais relacionados à autenticação.

   Recomendamos que você também consulte a documentação do respectivo tipo de conexão em Integration Connectors.

   1. Na etapa Local, escolha o local da conexão.
      1. Clique em Região e selecione um local na lista suspensa.
      2. Clique em Próxima.
   2. Na etapa Detalhes da conexão, forneça detalhes sobre a conexão:
      1. Conector: selecione o tipo de conector que você quer criar na lista suspensa. Para informações sobre a lista de conectores compatíveis, consulte Todos os Integration Connectors.
      2. Versão do conector: escolha uma versão disponível do tipo de conector selecionado na lista suspensa.
      3. Nome da conexão: insira um nome para a instância de conexão.
         Observação: os nomes de conexão precisam atender aos seguintes critérios:

         • Os nomes de conexões podem usar letras, números ou hifens.
         • As letras precisam ser minúsculas.
         • Os nomes das conexões precisam começar com uma letra e terminar com uma letra ou um número.
         • Os nomes das conexões não podem exceder 63 caracteres.
      4. (Opcional) Insira uma descrição para a instância de conexão.
      5. (Opcional) Marque Ativar o Cloud Logging para armazenar os dados de registro da instância de conexão.
      6. Conta de serviço: selecione uma conta de serviço que tenha os papéis necessários.
      7. (Opcional) Clique em Configurações avançadas para definir as configurações do nó da conexão.

         Para mais informações, consulte a documentação da conexão correspondente em Integration Connectors.

      8. (Opcional) Clique em + ADICIONAR RÓTULO para adicionar um rótulo à conexão na forma de um par de chave-valor.
      9. Clique em Próxima.
   3. Na etapa Autenticação, forneça os detalhes de autenticação da conexão.
      1. Os métodos de autenticação preenchidos durante essa etapa são baseados no tipo de conexão que está sendo criada.

         Tipos de conexão diferentes usam métodos de autenticação distintos. Para mais informações, consulte a seção Configurar a autenticação da documentação da conexão correspondente em Integration Connectors.

      2. Clique em Próxima.
   4. Revisão: revise os detalhes de conexão e autenticação.
   5. Clique em Criar.

---

Práticas recomendadas

• Para informações sobre os limites de uso que se aplicam à tarefa Conectores, consulte Limites de uso.
• Para informações sobre como resolver problemas de falhas em Conectores, consulte Usar registros para solucionar problemas e rastrear falhas do conector.

Estratégia de solução de erros

A estratégia de solução de erros para uma tarefa especifica a ação a ser realizada se a tarefa falhar devido a um erro temporário. Para mais informações sobre como usar uma estratégia de tratamento de erros e conhecer os diferentes tipos de estratégias de tratamento de erros, consulte Estratégias de tratamento de erros.