Atendimento de solicitações de API

---

Neste tutorial, descrevemos um caso de uso sobre como usar a Application Integration para rotear e buscar informações de uma solicitação de API de entrada.

Visão geral

Neste tutorial, você vai criar uma integração com um gatilho de API que recebe solicitações de API para recuperar informações do cliente. Dependendo do local da solicitação à API, a integração recupera os detalhes do cliente de um banco de dados MySQL ou Oracle.

Objetivos

Neste tutorial, mostramos como concluir as seguintes tarefas na sua integração:

• Adicionar um gatilho de API.
• Adicione e configure tarefas de conectores para conexões MySQL e Oracle.
• Adicionar e configurar tarefas de mapeamento de dados para extrair e mapear o payload da API.

Custos

Neste tutorial, você usará os seguintes componentes faturáveis do Google Cloud:

• Application Integration
• Integration Connectors
• Secret Manager

As instruções deste tutorial foram projetadas para manter seu uso de recursos dentro dos limites do nível Sempre gratuito do Google Cloud.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

4. Crie uma conta de serviço:

   1. No Console do Google Cloud, acesse a página Criar conta de serviço.

      Acesse "Criar conta de serviço"
   2. Selecione o projeto.

   3. No campo Nome da conta de serviço, insira um nome. O Console do Google Cloud preenche o campo ID da conta de serviço com base nesse nome.

      No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for quickstart.

   4. Clique em Criar e continuar.

   5. Conceda os papéis a seguir à conta de serviço: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager)

      Para conceder um papel, encontre a lista Selecionar um papel e escolha uma opção.

      Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.

      Observação: o campo Papel afeta quais recursos a conta de serviço pode acessar no projeto. É possível revogar esses papéis ou conceder outros papéis posteriormente. Em ambientes de produção, não conceda os papéis de proprietário, editor ou visualizador. Em vez disso, conceda um papel predefinido ou um papel personalizado que atenda às suas necessidades.
   6. Clique em Continuar.

   7. Clique em Concluído para terminar a criação da conta de serviço.

5. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

6. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

7. Crie uma conta de serviço:

   1. No Console do Google Cloud, acesse a página Criar conta de serviço.

      Acesse "Criar conta de serviço"
   2. Selecione o projeto.

   3. No campo Nome da conta de serviço, insira um nome. O Console do Google Cloud preenche o campo ID da conta de serviço com base nesse nome.

      No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for quickstart.

   4. Clique em Criar e continuar.

   5. Conceda os papéis a seguir à conta de serviço: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager)

      Para conceder um papel, encontre a lista Selecionar um papel e escolha uma opção.

      Para conceder outros papéis, clique em Adicionar outro papel e adicione cada papel adicional.

      Observação: o campo Papel afeta quais recursos a conta de serviço pode acessar no projeto. É possível revogar esses papéis ou conceder outros papéis posteriormente. Em ambientes de produção, não conceda os papéis de proprietário, editor ou visualizador. Em vez disso, conceda um papel predefinido ou um papel personalizado que atenda às suas necessidades.
   6. Clique em Continuar.

   7. Clique em Concluído para terminar a criação da conta de serviço.

Observação: todas as outras APIs do Google Cloud necessárias, como a API Application Integration, a API Secret Manager e a API Connectors, são ativadas durante a configuração da Application Integration. Saiba mais em Configurar o Application Integration.

Prepare o ambiente

Configurar um banco de dados MySQL

Conecte-se ao servidor MySQL e crie um banco de dados e uma tabela para usar neste tutorial. Neste tutorial, usamos um banco de dados que contém uma tabela chamada Customers com as seguintes linhas:

  +-------------+---------------+--------------------+------------------+
  | customer_id | customer_name | customer_emailID   | customer_city    |
  +-------------+---------------+--------------------+------------------+
  |           1 | Alex          | [e-mail]   | New York         |
  |           2 | Dana          | [e-mail]   | Seattle          |
  +-------------+---------------+--------------------+------------------+
  

Para saber mais sobre como criar e usar um banco de dados MySQL, consulte a documentação do MySQL.

Configurar um banco de dados Oracle

Conecte-se ao banco de dados Oracle e crie uma tabela para usar neste tutorial. Neste tutorial, usamos um banco de dados que contém uma tabela SQL chamada Customers com as seguintes linhas:

  +-------------+---------------+--------------------+------------------+
  | customer_id | customer_name | customer_emailID   | customer_city    |
  +-------------+---------------+--------------------+------------------+
  |           1 | Amal          | [e-mail]   | Delhi            |
  |           2 | Hao           | [e-mail]   | Beijing          |
  +-------------+---------------+--------------------+------------------+
  

Saiba como criar e usar um banco de dados Oracle na documentação da Oracle.

Configurar conexões

Para este tutorial, é preciso configurar as seguintes conexões nos Conectores de integração:

Dica:recomendamos que você crie as conexões a seguir na região us-central1(lowa).

Conexão do MySQL

Configure uma conexão MySQL nos Integration Connectors para receber as entidades de tabelas do Customer. Para informações sobre a configuração de um conector MySQL, consulte Conector MySQL.

Conexão com o Oracle DB

Configurar uma conexão do Oracle DB nos Integration Connectors para receber as entidades das tabelas do Customer. Para informações sobre a configuração de um conector do MySQL, consulte Conector do Oracle DB.

Criar integração

Para criar uma nova integração, execute as seguintes etapas:

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 Lista de integrações é exibida.
3. Clique em Criar integração e forneça os seguintes detalhes na página Criar integração:
   1. Nome da integração:insira api_fulfilment.
   2. Descrição:insira Demo integration created for tutorial.
   3. Região:selecione us-central1 na lista de regiões com suporte.
   4. Clique em Criar para abrir o editor de integração.

Configurar o gatilho de integração

Depois de criar a integração, é possível adicionar e configurar um gatilho de integração que invoque a integração para um evento identificado.

Neste tutorial, um gatilho de API é usado para invocar a integração em cada nova solicitação de API. Para adicionar e configurar um gatilho de API na sua integração do api_fulfilment, faça o seguinte:

1. No editor de integração, clique em Acionadores para exibir uma lista de acionadores disponíveis.
2. Clique e posicione o elemento Gatilho da API no editor de integração.

   O Application Integration preenche automaticamente o rótulo, o nome e o ID do acionador. O ID do acionador é gerado por máquina no formato api_trigger/TRIGGER_NAME e é usado na solicitação de API.

Nenhuma configuração adicional é necessária para esse gatilho.

Criar variáveis de integração

As variáveis de integração são semelhantes às usadas em uma linguagem de programação. Os dados nas variáveis podem ser lidos e gravados durante a execução da integração. Para criar as variáveis necessárias para este tutorial, faça o seguinte:

1. Clique em (Alternar painel) na barra de navegação do designer para abrir o painel Variables.
2. Clique em + Criar e crie as seguintes variáveis de integração:

   Nome da variável	Tipo de dados	Tipo variável
   location	STRING	Entrada para integração
   customer_id	STRING	Entrada para integração
   customer_record	JSON	Saída da integração

Recuperar dados do cliente do banco de dados MySQL

Se a solicitação da API de entrada tiver origem no local US, siga estas etapas para extrair os dados do cliente do banco de dados MySQL.

Conectar-se ao banco de dados MySQL

Siga as etapas abaixo para adicionar e configurar uma tarefa Conectores e recuperar os detalhes dos clientes da tabela Clientes do MySQL:

1. No editor de integração, clique em Tarefas para exibir uma lista das tarefas disponíveis.
2. Clique e coloque o elemento Conectores no editor de integração.
3. Selecione o elemento de tarefa Conectores no designer para visualizar o painel de configuração da tarefa Conectores.
4. Clique em e renomeie o rótulo Conectores como Fetch MySQL Data.
5. Clique em Configurar conector.
6. Faça o seguinte na página Editor de tarefas de conectores:
   1. Em Selecionar conexão, escolha a região us-central1.
   2. Selecione sua conexão do Salesforce na lista de conexões disponíveis.
   3. Clique em Próxima.
   4. Em Tipo, escolha Entidades.
   5. Em Definir entidades/ações, selecione Clientes na lista de entidades disponíveis e escolha Obter como a Operação.
   6. Clique em Concluído para concluir a configuração da conexão e feche o painel.

Mapear o ID de cliente para o conector do MySQL

Uma tarefa de Mapeamento de dados é usada para mapear o ID de cliente para o conector do MySQL. Para adicionar e configurar o mapeamento de dados na sua integração, faça o seguinte:

1. No editor de integração, clique em Tarefas para exibir uma lista das tarefas disponíveis.
2. Clique e posicione o elemento Mapeamento de dados no editor de integração.
3. Selecione o elemento Mapeamento de dados no designer para visualizar o painel de configuração da tarefa.
4. Clique em e renomeie a tarefa Mapeamento de dados como Map to MySQL.
5. Clique em Abrir editor de mapeamento de dados.

   O Editor de mapeamento de dados permite mapear variáveis de entrada para as variáveis de saída desejadas, usando as funções de transformação disponíveis. A saída é disponibilizada como uma variável para qualquer outra tarefa ou gatilho de integração. Para mais detalhes sobre variáveis de mapeamento, consulte Adicionar um mapeamento.

6. Associe a variável de integração do acionador (customer_id) à variável de entrada entityId(Fetch MySQL Data) do conector gerado automaticamente.

   Quando o mapeamento for concluído, feche o painel. Todas as alterações serão salvas automaticamente.

7. Adicione uma conexão de borda da tarefa Mapear para MySQL ao conector Buscar dados do MySQL.

Recuperar detalhes do cliente do MySQL

Para recuperar os detalhes do cliente do conector do MySQL, faça o seguinte:

1. No editor de integração, clique em Tarefas para exibir uma lista das tarefas disponíveis.
2. Clique e posicione o elemento Mapeamento de dados no editor de integração.
3. Clique no elemento Data Mapping no designer para visualizar o painel de configuração da tarefa.
4. Clique em e renomeie a tarefa Mapeamento de dados como Get MySQL data.
5. Clique em Abrir editor de mapeamento de dados.
6. Mapear a variável de saída do MySQL (connectorOutputPayload (Fetch MySQL Data)) para a variável de integração customer_record.

   Quando o mapeamento for concluído, feche o painel. Todas as alterações serão salvas automaticamente.

7. Adicione uma conexão de borda do conector Buscar dados do MySQL à tarefa Receber dados do MySQL.

Recuperar dados do cliente do banco de dados Oracle

Se a solicitação da API de entrada tiver origem no local APAC, siga as etapas abaixo para recuperar dados do cliente do banco de dados Oracle.

Conectar-se ao banco de dados Oracle

Siga as etapas abaixo para adicionar e configurar uma tarefa Conectores e recuperar os detalhes dos clientes da tabela Customers do Oracle:

1. No editor de integração, clique em Tarefas para exibir uma lista das tarefas disponíveis.
2. Clique e coloque o elemento Conectores no editor de integração.
3. Selecione o elemento de tarefa Conectores no designer para visualizar o painel de configuração da tarefa Conectores.
4. Clique em e renomeie o rótulo Conectores como Fetch Oracle Data.
5. Clique em Configurar conector.
6. Faça o seguinte na página Editor de tarefas de conectores:
   1. Em Selecionar conexão, escolha a região us-central1.
   2. Selecione sua conexão do Salesforce na lista de conexões disponíveis.
   3. Clique em Próxima.
   4. Em Tipo, escolha Entidades.
   5. Em Definir entidades/ações, selecione Clientes na lista de entidades disponíveis e escolha Obter como a Operação.
   6. Clique em Concluído para concluir a configuração da conexão e feche o painel.

Mapear o ID de cliente para o conector do Oracle

Para adicionar e configurar o mapeamento de dados na sua integração, faça o seguinte:

1. No editor de integração, clique em Tarefas para exibir uma lista das tarefas disponíveis.
2. Clique e posicione o elemento Mapeamento de dados no editor de integração.
3. Selecione o elemento Mapeamento de dados no designer para visualizar o painel de configuração da tarefa.
4. Clique em e renomeie a tarefa Mapeamento de dados como Map to Oracle.
5. Clique em Abrir editor de mapeamento de dados.
6. Associe a variável de integração do acionador (customer_id) à variável de entrada entityId(Fetch Oracle Data) do conector gerado automaticamente.

   Quando o mapeamento for concluído, feche o painel. Todas as alterações serão salvas automaticamente.

7. Adicione uma conexão de borda da tarefa Mapear para Oracle ao conector Buscar dados do Oracle.

Recuperar detalhes do cliente da Oracle

Para recuperar os detalhes do cliente do conector Oracle, faça o seguinte:

1. No editor de integração, clique em Tarefas para exibir uma lista das tarefas disponíveis.
2. Clique e posicione o elemento Mapeamento de dados no editor de integração.
3. Clique no elemento Data Mapping no designer para visualizar o painel de configuração da tarefa.
4. Clique em e renomeie a tarefa Mapeamento de dados como Get Oracle data.
5. Clique em Abrir editor de mapeamento de dados.
6. Mapeie a variável de saída do Oracle (connectorOutputPayload (Fetch Oracle Data)) para a variável de integração customer_record.

   Quando o mapeamento for concluído, feche o painel. Todas as alterações serão salvas automaticamente.

7. Adicione uma conexão de borda do conector Buscar dados do Oracle à tarefa Acessar dados do Oracle.

Adicionar condição de borda

Uma condição de borda permite especificar as condições que precisam ser atendidas para que o controle de uma integração passe para a tarefa conectada pela borda. Agora que você adicionou e configurou as tarefas necessárias, pode adicionar uma condição de borda para definir o fluxo da integração.

A seguinte condição de borda controla o fluxo de integração com base na variável de integração location:

1. Adicione uma conexão de borda do gatilho da API à tarefa Mapear para o MySQL com a seguinte condição de borda:

     $location$ = "US"

2. Adicione outra conexão de borda do gatilho API à tarefa Mapear para Oracle com a seguinte condição de borda:

     $location$ = "APAC"

Exemplo de fluxo de integração

A figura a seguir mostra um exemplo de layout da integração criada usando este tutorial.

Integração de publicação

Para publicar a integração, clique em Publicar na barra de ferramentas do editor de integração.

Após a publicação da integração, você poderá ver e inspecionar os registros de execução da integração publicada. Para acessar registros, clique em Exibir registros de execução para esta integração. A página Registros de execução é exibida.

Testar a integração

Testar a integração no editor de integração

Para testar a integração usando o editor de integração, siga estas etapas:

1. Clique em Test na barra de ferramentas do editor de integração.

   A caixa de diálogo Testar integração é exibida.

2. Você vai precisar inserir os valores de teste das variáveis de entrada de integração. Para os fins deste teste, faça o seguinte:
   • customer_id::insira 1.
   • location: insira APAC.
3. Clique em Testar integração.

A integração foi executada, e o seguinte valor do cliente é exibido:

{
  "CUSTOMER_ID": 1,
  "CUSTOMER_NAME": "Amal"
  "CUSTOMER_EMAILID": "[e-mail] "
  "CUSTOMER_CITY": "Delhi"
}

Para mais informações sobre testes, consulte Testar e publicar integrações.

Testar usando uma chamada da API REST

Agora que a integração foi publicada e está em execução, você pode invocá-la usando a seguinte chamada REST POST:

URL:

https://integrations.googleapis.com/v1/projects/project-name/locations/-/integrations/api_fulfilment:execute 

Corpo da solicitação:

{"trigger_id":"api_trigger/api_fulfilment_API_1"}

Exemplo: fazer uma solicitação de API com entradas personalizadas

Observação:o exemplo a seguir usa curl, que normalmente vem pré-instalado para os sistemas operacionais Linux e macOS. Caso não tenha o curl, faça o download dele na página de versões e downloads do curl.

curl -v -X POST -H "Content-Type: application/json" 'https://integrations.googleapis.com/v1/projects/connectors-ip-test/locations/us-central1/integrations/api-fulfillment-integration:execute' -H "Authorization: Bearer $(gcloud auth AUTH_PROFILE)" -d  '{ "triggerId": "api_trigger/api-fulfillment-integration_API_1", "inputParameters": { "customer_id": {"string_value": 1}, "location" : {"string_value" : "US"}} }'

A API retorna a resposta de execução da integração que contém todo o JSON a seguir:

  {
    "CUSTOMER_ID": 2,
    "CUSTOMER_NAME": "Dana"
    "CUSTOMER_EMAILID": "[e-mail] "
    "CUSTOMER_CITY": "Seattle"
  }
  

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados neste tutorial, cancele a publicação da integração e exclua as conexões criadas nos Integration Connectors.

• Para cancelar a publicação da integração, clique em Cancelar publicação na barra de ferramentas do editor de integração. Consulte Excluir integrações para mais informações.
• Para informações sobre como excluir uma conexão, consulte Gerenciar conectores.