Consulte os conetores suportados para a solução Application Integration.

Tarefa de conetores

A tarefa Conetores permite-lhe estabelecer ligação rápida e segura aos vários serviços Google Cloud e outras aplicações empresariais a partir da sua integração através dos conetores predefinidos disponíveis nos Conetores de integração.

Para ver a lista de todos os conetores suportados para a integração de aplicações, consulte a referência de conetores.

Antes de começar

  • Certifique-se de que tem a função IAM de administrador de conetores (roles/connectors.admin) concedida no seu projeto do Google Cloud. Para informações sobre a concessão de funções, consulte o artigo Faça a gestão do acesso.
  • Saiba mais sobre os conceitos gerais dos conetores de integração.
  • Para estabelecer ligação aos serviços do Google Cloud e a outras aplicações empresariais através de um conector, certifique-se de que anexou uma conta de serviço gerida pelo utilizador à sua integração. Se a sua integração não tiver uma conta de serviço gerida pelo utilizador configurada, é utilizada por predefinição a conta de serviço predefinida (service-PROJECT_NUMBER@gcp-sa-integrations.iam.gserviceaccount.com) para autenticação.
  • Certifique-se de que a sua conta de serviço tem a função de IAM necessária. Para obter informações sobre a atribuição de funções a uma conta de serviço, consulte o artigo Faça a gestão do acesso às contas de serviço.

Adicione uma tarefa de conetores

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

  1. Na Google Cloud consola, aceda à página Application Integration.

    Aceda à solução Application Integration

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

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

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

    Se estiver a criar uma nova integração:

    1. Introduza um nome e uma descrição no painel Criar integração.
    2. Selecione uma região para a integração.
    3. Selecione uma conta de serviço para a integração. Pode alterar ou atualizar os detalhes da conta de serviço de uma integração em qualquer altura no painel Resumo da integração na barra de ferramentas de integração.
    4. Clique em Criar. A integração recém-criada é aberta no editor de integração.

  4. Na barra de navegação do editor de integração, clique em Tasks para ver a lista de tarefas e conetores disponíveis.

    5. Imagem que mostra a tarefa de conetores

  5. Se quiser configurar uma nova ligação, clique e coloque o elemento Conetores no editor de integração. Em seguida, clique em Configurar conetor para configurar a associação.

    Imagem que mostra a lista de tarefas do conetor Imagem que mostra a lista de tarefas do conetor

  6. Se tiver uma associação existente, clique no separador Conetores para ver as associações criadas recentemente. Também pode pesquisar um conetor, uma associação ou uma tarefa introduzindo o nome no campo Pesquisar.

    Imagem que mostra a capacidade de pesquisa da tarefa de conectores

  7. Clique e coloque o elemento Conetores configurado no editor de integração. Para ver informações sobre como configurar uma tarefa de conetor, consulte o artigo Configure a tarefa de conetores.

Configure a tarefa Conetores

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

  1. Clique no elemento da tarefa Conetores no criador para ver o painel de configuração da tarefa Conetores.

    Opcionalmente, clique em para mudar o nome da tarefa.

  2. Clique em Configurar conetor.
  3. Pode selecionar uma associação existente na região ou criar uma nova associação. Para configurar uma associação existente, conclua os passos seguintes na página Editor de tarefas de conetores.

    A imagem seguinte mostra um esquema de exemplo da página Editor de tarefas de conectores. Imagem que mostra a caixa de diálogo da tarefa de configuração do conector Imagem que mostra a caixa de diálogo da tarefa de configuração do conector

    1. Na secção Selecionar ligação, selecione a região da ligação.
    2. Escolha uma associação existente na lista de associações disponíveis na região selecionada.
    3. Clicar em Seguinte.
    4. Na lista Tipo, selecione Entidades ou Ações.
      • Se selecionar Entidades, a lista de entidades suportadas para a associação é apresentada na secção Definir entidades/ações. Selecione uma entidade, seguida da operação que quer realizar nessa entidade.
      • Se selecionar Ações, a lista de ações suportadas para a associação é apresentada na coluna Definir entidades/ações. Selecione uma ação para a associação.
        • As entidades e as ações suportadas baseiam-se no tipo de conetor. Para ver a lista de todos os conetores suportados para a integração de aplicações, consulte a referência de conetores. Para ver as ações e as entidades suportadas para um conetor, consulte a documentação do conetor específico.

        Se o conector suportar consultas SQL personalizadas, pode selecionar a opção Executar consulta personalizada na lista Ações. Para ver informações sobre como adicionar uma consulta SQL personalizada para o seu conetor, consulte o artigo Ação: executar consulta SQL personalizada.

    5. Clique em Concluído para concluir a configuração da associação e fechar o painel.

Configure as variáveis de entrada e saída da tarefa

O painel de configuração da tarefa Conectores apresenta as variáveis de entrada da tarefa e saída da tarefa que são geradas automaticamente com base na entidade e operação ou na ação selecionada na caixa de diálogo Configurar tarefa do conector. Estas variáveis são configuráveis e estão acessíveis como entradas para a tarefa atual ou como saídas para tarefas subsequentes ou condições na integração atual.

Para configurar as variáveis Entrada da tarefa ou Saída da tarefa, clique na variável respetiva para abrir o painel Configurar variável e siga estes passos:

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

Para mais informações sobre os parâmetros de entrada e saída da tarefa Conectores, consulte o artigo Operações de entidades.

Configure a substituição da autenticação

Para permitir que a ligação aceite dinamicamente uma autenticação de back-end diferente durante a execução, certifique-se de que, nos Integration Connectors, selecionou a opção Ativar substituição de autenticação para a sua ligação.

Para configurar a substituição da autenticação, faça o seguinte:

  1. Clique no elemento da tarefa de conetores no criador para ver o painel de configuração da tarefa Conetores.
  2. Expanda a secção Entrada de tarefas. O campo Credenciais de utilizador final está definido para uma variável dynamicAuthConfig.

    Credenciais de utilizador final Credenciais de utilizador final

    Em seguida, faça o seguinte:

    1. Clique na variável dynamicAuthConfig. É apresentado o painel Editar variável.

      Para substituir a autenticação, tem de fornecer os valores de autenticação quando testar a integração.

      Edite a variável euc dinâmica Edite a variável euc dinâmica

      Para o fazer, siga estes passos:

      1. Na lista Tipo de variável, selecione Entrada para integração.
      2. Nas opções do esquema JSON, pode validar o tipo de autenticação configurado para a ligação. Use este esquema para substituir o valor de autenticação quando testar a integração.

        Teste a integração para a substituição da autorização Teste a integração para a substituição da autorização

    Em alternativa, pode transmitir a autenticação como o cabeçalho HTTP selecionando a caixa de verificação Usar cabeçalho HTTPS para configuração de autorização na secção Entrada da tarefa do painel de configuração da tarefa Conetores.

    Teste a integração transmitindo a autenticação como o cabeçalho HTTP Teste a integração transmitindo a autenticação como o cabeçalho HTTP

Ações e operações de entidades

Pode realizar operações CRUD (criar, ler, atualizar e eliminar) nas entidades de um conector. Cada uma destas operações de entidades tem um conjunto diferente de parâmetros de entrada e saída. A tabela seguinte apresenta os parâmetros de entrada e saída das várias operações de entidades.

Nome da operação Parâmetros de entrada Parâmetros de saída
Lista
  • listEntitiesPageSize
  • listEntitiesPageToken
  • listEntitiesSortByColumns
  • filterClause
  • connectorOutputPayload
  • listEntitiesNextPageToken
Obter entityId connectorOutputPayload
Criar connectorInputPayload connectorOutputPayload
Atualizar
  • connectorInputPayload
  • entityId
  • filterClause
 connectorOutputPayload
Eliminar
  • entityId
  • filterClause
 N/A

Parâmetros de entrada

A tabela seguinte descreve os parâmetros de entrada para as várias operações de entidades.

Nome do parâmetro Tipo de dados Descrição
entityId String

Um identificador exclusivo da linha à qual quer aceder.

Normalmente, o entityId é um valor de chave primária de uma tabela ou um conjunto de dados. Se 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 comunica um erro de tempo de execução e a tarefa Conetores falha.

Por exemplo, para obter uma linha específica de uma tabela do MySQL, o valor de entityId é o valor da chave principal na tabela.
connectorInputPayload JSON Os dados reais a adicionar ou atualizar numa entidade. O exemplo seguinte mostra o fragmento JSON de dados de uma linha a adicionar numa tabela: 
{
"employee_first_name": "John",
"employee_emailID": "test-05@test.com"
}

Neste exemplo, employee_first_name e employee_emailID são os nomes das colunas com os valores correspondentes John e test-05@test.com.
filterClause String Restringe o resultado das operações com base numa condição. Para mais informações sobre como adicionar uma cláusula de filtro, consulte o artigo Adicione um filtro para uma operação.
listEntitiesPageSize Número inteiro

Especifica o número de resultados que devem ser devolvidos numa página.

Uma página é um agrupamento lógico dos registos num conjunto de resultados. O conceito de página é útil quando espera um grande número de registos no conjunto de resultados. Se o conjunto de resultados for grande, a tarefa Conetores pode falhar, uma vez que existe um limite no tamanho dos dados que a tarefa Conetores pode processar. Ao dividir o conjunto de resultados em partes mais pequenas, pode evitar este problema.

Por exemplo, se estiver à espera de 1000 registos no conjunto de resultados, pode definir o listEntitiesPageSize como 100. Assim, quando a tarefa Conetores é executada pela primeira vez, devolve os primeiros 100 registos, os 100 registos seguintes na segunda execução e assim sucessivamente.

listEntitiesPageToken String

Um identificador de página (token) que lhe permite aceder a uma página específica.

Pode obter o valor de um token de página a partir do parâmetro de saída listEntitiesNextPageToken. Como cada página tem um token exclusivo, tem a flexibilidade de aceder a qualquer página que pretender no conjunto de resultados. Para compreender a utilização deste parâmetro, leia também a descrição do parâmetro de saída listEntitiesNextPageToken.
listEntitiesSortByColumns Matriz de strings Nome da coluna pela qual quer ordenar o conjunto de resultados.

Parâmetros de saída

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

Nome do parâmetro Tipo de dados Descrição
connectorOutputPayload JSON O resultado de uma operação no formato JSON.
listEntitiesNextPageToken String

Um identificador gerado pelo sistema para uma página. Pode considerar o token como um ponteiro através do qual pode aceder a uma página específica do conjunto de resultados.

Se dividiu o conjunto de resultados em várias páginas definindo o parâmetro listEntitiesPageSize, precisa de um mecanismo para navegar pelas páginas. O parâmetro de saída listEntitiesNextPageToken permite-lhe fazer exatamente isso. Sempre que a tarefa Conetores é executada, o sistema gera um token para a página seguinte e define o valor de listEntitiesNextPageToken para o token gerado recentemente. Em seguida, pode usar este token para aceder à página seguinte no conjunto de resultados. Para aceder à página seguinte, tem de definir o parâmetro de entrada listEntitiesPageToken para o valor do token da página seguinte.

Por exemplo, considere que 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==. Em seguida, pode definir o parâmetro de entrada listEntitiesPageToken para este valor do token para obter a página seguinte na execução subsequente da tarefa Connectors.

Se o conjunto de resultados tiver um grande número de páginas, pode considerar usar a tarefa While Loop para obter a página seguinte e usar a tarefa Mapeamento de dados para atribuir automaticamente valores de tokens de páginas ao parâmetro de entrada listEntitiesPageToken após cada execução. Mapeie listEntitiesNextPageToken da última iteração do ciclo para listEntitiesPageToken no LIST Operation da tarefa Conetores da iteração do ciclo atual. A tarefa While Loop termina quando listEntitiesNextPageToken é NULL, o que implica que não existem mais páginas.

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

Pode restringir os registos processados pela tarefa Conectores através da variável cláusula Filter, que está disponível como entrada de tarefa. Por exemplo, no caso de uma operação de eliminação, pode adicionar uma cláusula de filtro para eliminar registos com um orderId específico.

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

  • Lista
  • Eliminar
  • Atualizar

Quando seleciona qualquer uma destas operações, a secção Entrada de tarefas da tarefa Conetores apresenta automaticamente o campo Cláusula de filtro.

Adicione uma cláusula de filtro

Para adicionar uma cláusula de filtro, siga estes passos:

  1. Clique no elemento da tarefa Conetores no criador para ver o painel de configuração da tarefa Conetores.
  2. Expanda a secção Entrada de tarefas e clique na variável de string filterClause(Connectors).

    É apresentada a caixa de diálogo Configurar variável.

  3. Introduza a cláusula de filtro (seguindo a sintaxe da cláusula) no campo Valor predefinido.
  4. Clique em Guardar.

Sintaxe e exemplos de cláusulas de filtro

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

Utilização de variáveis na cláusula de filtro

Não pode usar diretamente uma variável de integração numa cláusula de filtro. Se quiser usar uma variável de integração, primeiro tem de configurar uma tarefa de mapeamento de dados para criar um mapeamento entre a variável de integração e a cláusula de filtro.

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

Entrada Resultado
PRIMARY_KEY_ID = ' .CONCAT(INTEGRATION_VARIABLE) .CONCAT(') filterClause(Connectors)
Em que PRIMARY_KEY_ID = ' é introduzido como um Valor na linha de entrada.

Ação: executar consulta SQL personalizada

Para criar uma consulta personalizada, siga estes passos:

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

    Imagem que mostra a ação execute-custom-query Imagem que mostra a ação execute-custom-query

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

      Valor predefinido: 180 segundos.

    2. No campo Número máximo de linhas, introduza o número máximo de linhas a devolver da base de dados.

      Valor predefinido: 25.

    3. Para atualizar a consulta personalizada, clique em Editar script personalizado. É apresentada a caixa de diálogo Editor de scripts.

      imagem a mostrar custom-sql-query imagem a mostrar custom-sql-query

    4. Na caixa de diálogo Editor de scripts, introduza a consulta SQL e clique em Guardar.

      Pode usar um ponto de interrogação (?) numa declaração SQL para representar um único parâmetro que tem de 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 para a coluna LastName: 

      SELECT * FROM Employees where LastName=?

    5. Se usou pontos de interrogação na sua consulta SQL, tem de adicionar o parâmetro clicando em + Adicionar nome do parâmetro para cada ponto de interrogação. Durante a execução da integração, estes parâmetros substituem os pontos de interrogação (?) na consulta SQL sequencialmente. Por exemplo, se adicionou três pontos de interrogação (?), tem de adicionar três parâmetros por ordem de sequência.

      imagem que mostra add-query-param imagem que mostra add-query-param

      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, introduza o valor do parâmetro.
      3. Para adicionar vários parâmetros, clique em + Adicionar parâmetro de consulta.

      6. A ação Executar consulta personalizada não suporta variáveis de matriz.

Atualização do esquema

Todas as entidades e ações têm um esquema associado. Por exemplo, um esquema de ação tem os detalhes dos parâmetros, como os nomes dos parâmetros e o respetivo tipo de dados. O esquema (metadados) para entidades e ações é obtido pela ligação no momento da execução a partir do seu back-end. Se existirem atualizações ao esquema, estas não são refletidas automaticamente nas suas associações existentes. Tem de atualizar o esquema manualmente. Para ver o esquema atualizado nas tarefas do conector existentes, siga estes passos:
  1. Nos Integration Connectors, abra a página Detalhes da ligação da ligação e, de seguida, clique em Atualizar esquema de ligação.
  2. Na integração de aplicações, tem de reconfigurar a tarefa do conector existente para a mesma ligação.

Criação de associações inline

Pode usar a tarefa Conetores para criar diretamente uma nova associação nos conetores de integração.

Antes de começar

Crie uma nova ligação

Para criar uma nova associação a partir da integração de aplicações, siga estes passos:

  1. Clique no elemento da tarefa Conetores no criador para ver o painel de configuração da tarefa Conetores.
  2. Clique em Configurar conetor.

    É apresentada a página Editor de tarefas de conetores.

  3. Ignore o campo Região.
  4. Clique em Associação e selecione a opção Criar associação no menu pendente.
  5. Conclua os passos seguintes no painel Criar associação:
    1. No passo Localização, escolha a localização da associação.
      1. Clique em Região e selecione uma localização na lista pendente.
      2. Clicar em Seguinte.
    2. No passo Detalhes da associação, faculte detalhes sobre a associação:
      1. Conetor: selecione o tipo de conetor que quer criar na lista pendente. Para ver informações sobre a lista de conetores suportados, consulte o artigo Todos os conetores de integração.
      2. Versão do conetor: escolha uma versão disponível do tipo de conetor selecionado na lista pendente.
      3. Nome da associação: introduza um nome para a instância da associação.
      4. (Opcional) Introduza uma Descrição para a instância da associação.
      5. (Opcional) Selecione Ativar Cloud Logging para armazenar os dados de registo da instância de associação.
      6. Conta de serviço: selecione uma conta de serviço que tenha as funções necessárias.
      7. (Opcional) Clique em Definições avançadas para configurar as definições do nó de ligação.

        Para mais informações, consulte a documentação de ligação respetiva em Conetores de integração.

      8. (Opcional) Clique em + ADICIONAR ETIQUETA para adicionar uma etiqueta à associação sob a forma de um par de chave/valor.
      9. Clicar em Seguinte.
    3. No passo Autenticação, indique os detalhes de autenticação da associação.
      1. Os métodos de autenticação preenchidos durante este passo baseiam-se no tipo de ligação que está a ser criada.

        Os diferentes tipos de ligação usam diferentes métodos de autenticação. Para mais informações, consulte a secção Configure a autenticação da documentação de ligação respetiva nos conetores de integração.

      2. Clicar em Seguinte.
    4. Rever: reveja os detalhes da ligação e da autenticação.
    5. Clique em Criar.

Práticas recomendadas

Estratégia de processamento de erros

Uma estratégia de processamento de erros para uma tarefa especifica a ação a realizar se a tarefa falhar devido a um erro temporário. Para obter informações sobre como usar uma estratégia de processamento de erros e conhecer os diferentes tipos de estratégias de processamento de erros, consulte o artigo Estratégias de processamento de erros.

Preços

O acionador do Cloud Pub/Sub e o acionador do Salesforce não requerem a criação de um conetor. No entanto, se usar a tarefa Connectors para estabelecer ligação ao Pub/Sub ou ao Salesforce, a utilização do conetor é faturada. Para ver informações sobre preços, consulte a secção Preços da integração de aplicações.

Quotas e limites

Para informações sobre quotas e limites, consulte o artigo Quotas e limites.

O que se segue?