Cumprimento de pedidos de API

Este tutorial descreve um exemplo de utilização sobre como pode usar a Application Integration para encaminhar e obter informações para um pedido de API de entrada.

Vista geral

Neste tutorial, vai criar uma integração com um acionador de API que recebe pedidos de API para obter informações dos clientes. Consoante a localização do pedido da API, a integração obtém os detalhes do cliente a partir de uma base de dados MySQL ou uma base de dados Oracle.

Objetivos

Este tutorial mostra como concluir as seguintes tarefas na sua integração:

• Adicione um acionador de API.
• Adicione e configure tarefas de conetores para ligações MySQL e Oracle.
• Adicione e configure tarefas de mapeamento de dados para extrair e mapear a carga útil da API.

Custos

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

• Integração de aplicações
• Conetores de integração
• Secret Manager

As instruções neste tutorial foram concebidas para manter a sua utilização de recursos dentro dos limites do nível Sempre grátis do Google Cloud.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Create a service account:

1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin). Learn how to grant roles.

2. In the Google Cloud console, go to the Create service account page.

   Go to Create service account
3. Select your project.

4. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

   In the Service account description field, enter a description. For example, Service account for quickstart.

5. Click Create and continue.

6. Grant the following roles to the service account: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

   To grant a role, find the Select a role list, then select the role.

   To grant additional roles, click Add another role and add each additional role.

   Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
7. Click Continue.

8. Click Done to finish creating the service account.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Create a service account:

1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin). Learn how to grant roles.

2. In the Google Cloud console, go to the Create service account page.

   Go to Create service account
3. Select your project.

4. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

   In the Service account description field, enter a description. For example, Service account for quickstart.

5. Click Create and continue.

6. Grant the following roles to the service account: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

   To grant a role, find the Select a role list, then select the role.

   To grant additional roles, click Add another role and add each additional role.

   Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
7. Click Continue.

8. Click Done to finish creating the service account.

Nota: todas as outras APIs Google Cloud necessárias, como a API Application Integration, a API Secret Manager e a API Connectors, são ativadas durante a configuração do Application Integration. Para mais detalhes, consulte o artigo Configure a integração de aplicações.

Prepare o seu ambiente

Configure uma base de dados MySQL

Estabeleça ligação ao seu servidor MySQL e crie uma base de dados e uma tabela para usar neste tutorial. Este tutorial usa uma base de dados que contém uma tabela denominada 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 ver informações sobre como criar e usar uma base de dados do MySQL, consulte a documentação do MySQL.

Configure uma base de dados Oracle

Estabeleça ligação à sua base de dados Oracle e crie uma tabela para usar neste tutorial. Este tutorial usa uma base de dados que contém uma tabela SQL denominada Customers com as seguintes linhas:

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

Para obter informações sobre como criar e usar uma base de dados do Oracle, consulte a documentação do Oracle.

Configurar ligações

Para este tutorial, tem de configurar as seguintes associações em Conetores de integração:

Dica: recomendamos que crie as seguintes associações na região us-central1(lowa).

Ligação MySQL

Configure uma ligação MySQL nos Integration Connectors para obter as entidades das tabelas Customer. Para obter informações sobre a configuração de um conetor do MySQL, consulte o artigo Conetor do MySQL.

Ligação à base de dados Oracle

Configure uma ligação à base de dados Oracle nos Integration Connectors para obter as entidades das tabelas Customer. Para obter informações sobre a configuração de um conetor do MySQL, consulte o artigo Conetor da base de dados Oracle.

Criar integração

Para criar uma nova integração, siga estes passos:

1. Na Google Cloud Console, aceda à página Integração de aplicações.

   Aceda à solução Application Integration

2. Clique em Integrações no menu de navegação do lado esquerdo para abrir a página Integrações.
3. Clique em Criar integração e indique os seguintes detalhes na página Criar integração:
   1. Nome da integração: introduza api_fulfilment.
   2. Descrição: introduza Demo integration created for tutorial.
   3. Região: selecione us-central1 na lista de regiões suportadas.
   4. Clique em Criar para abrir o editor de integração.

Configure o acionador de integração

Depois de criar com êxito a integração, pode adicionar e configurar um acionador de integração que invoca a integração para um evento identificado.

Para este tutorial, é usado um acionador de API para invocar a integração para cada novo pedido de API. Para adicionar e configurar um acionador de API na integração do api_fulfilment, faça o seguinte:

1. No editor de integração, clique em Acionadores para apresentar uma lista de acionadores disponíveis.
2. Clique e coloque o elemento Acionador de API no editor de integração.

   A integração de aplicações preenche automaticamente a etiqueta do acionador, o nome do acionador e o ID do acionador. O ID do acionador é um ID gerado pela máquina no formato api_trigger/TRIGGER_NAME e é usado no pedido da API.

Não é necessária nenhuma configuração adicional para este acionador.

Crie variáveis de integração

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

1. Clique em (Ativar/desativar painel) na barra de navegação do criador para apresentar o painel Variáveis.
2. Clique em + Criar e crie as seguintes variáveis de integração:

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

Obtenha dados de clientes da base de dados MySQL

Se o pedido da API de entrada for da localização US, faça o seguinte para obter dados dos clientes da base de dados MySQL.

Associe à base de dados MySQL

Execute os passos seguintes para adicionar e configurar uma tarefa Connectors para obter os detalhes dos clientes da tabela Customers do MySQL:

1. No editor de integração, clique em Tasks para apresentar uma lista de tarefas disponíveis.
2. Clique e coloque o elemento Conetores no editor de integração.
3. Selecione o elemento de tarefa Conetores no criador para ver o painel de configuração da tarefa de conetores.
4. Clique em e mude o nome da etiqueta Conectores para Fetch MySQL Data.
5. Clique em Configurar conetor.
6. Faça o seguinte na página Editor de tarefas de conetores:
   1. Em Selecionar ligação, escolha a região us-central1.
   2. Selecione a sua ligação do Salesforce na lista de ligações disponíveis.
   3. Clicar em Seguinte.
   4. Em Tipo, escolha Entidades.
   5. Em Definir entidades/ações, selecione Clientes na lista de entidades disponíveis e, de seguida, selecione Obter como Operação.
   6. Clique em Concluído para concluir a configuração da associação e fechar o painel.

Mapeie o ID de cliente para o conetor do MySQL

Uma tarefa de mapeamento de dados é usada para mapear o ID do cliente para o conetor 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 Tasks para apresentar uma lista de tarefas disponíveis.
2. Clique e coloque o elemento Mapeamento de dados no editor de integração.
3. Selecione o elemento Mapeamento de dados no criador para ver o painel de configuração da tarefa.
4. Clique em e mude o nome da tarefa Mapeamento de dados para Map to MySQL.
5. Clique em Abrir editor de mapeamento de dados.

   O editor de mapeamento de dados permite-lhe mapear variáveis de entrada para as variáveis de saída pretendidas, através das funções de transformação disponíveis. A saída fica então disponível como uma variável para qualquer outra tarefa de integração ou acionador. Para ver mais detalhes sobre como mapear variáveis, consulte o artigo Adicione um mapeamento.

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

   Quando o mapeamento estiver concluído, feche o painel. As alterações são guardadas automaticamente.

7. Adicione uma ligação de aresta da tarefa Mapear para MySQL ao conetor Obter dados do MySQL.

Obtenha detalhes de clientes do MySQL

Para obter os detalhes do cliente a partir do conetor do MySQL, faça o seguinte:

1. No editor de integração, clique em Tasks para apresentar uma lista de tarefas disponíveis.
2. Clique e coloque o elemento Mapeamento de dados no editor de integração.
3. Clique no elemento Mapeamento de dados no criador para ver o painel de configuração da tarefa.
4. Clique em e mude o nome da tarefa Mapeamento de dados para Get MySQL data.
5. Clique em Abrir editor de mapeamento de dados.
6. Mapeie a variável de saída do MySQL—connectorOutputPayload (Fetch MySQL Data)—com a variável de integração customer_record.

   Quando o mapeamento estiver concluído, feche o painel. As alterações são guardadas automaticamente.

7. Adicione uma ligação de aresta do conetor Obter dados do MySQL à tarefa Obter dados do MySQL.

Recupere dados de clientes da base de dados Oracle

Se o pedido da API de entrada for da localização APAC, faça o seguinte para obter os dados do cliente da base de dados Oracle.

Associe à base de dados Oracle

Execute os passos seguintes para adicionar e configurar uma tarefa Connectors para obter os detalhes dos clientes da tabela Customers do Oracle:

1. No editor de integração, clique em Tasks para apresentar uma lista de tarefas disponíveis.
2. Clique e coloque o elemento Conetores no editor de integração.
3. Selecione o elemento de tarefa Conetores no criador para ver o painel de configuração da tarefa de conetores.
4. Clique em e mude o nome da etiqueta Conectores para Fetch Oracle Data.
5. Clique em Configurar conetor.
6. Faça o seguinte na página Editor de tarefas de conetores:
   1. Em Selecionar ligação, escolha a região us-central1.
   2. Selecione a sua ligação do Salesforce na lista de ligações disponíveis.
   3. Clicar em Seguinte.
   4. Em Tipo, escolha Entidades.
   5. Em Definir entidades/ações, selecione Clientes na lista de entidades disponíveis e, de seguida, selecione Obter como Operação.
   6. Clique em Concluído para concluir a configuração da associação e fechar o painel.

Mapeie o ID de cliente para o conetor da 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 Tasks para apresentar uma lista de tarefas disponíveis.
2. Clique e coloque o elemento Mapeamento de dados no editor de integração.
3. Selecione o elemento Mapeamento de dados no criador para ver o painel de configuração da tarefa.
4. Clique em e mude o nome da tarefa Mapeamento de dados para Map to Oracle.
5. Clique em Abrir editor de mapeamento de dados.
6. Mapeie a variável de integração—customer_id—do acionador à variável de entrada—entityId(Fetch Oracle Data)—do conector gerado automaticamente.

   Quando o mapeamento estiver concluído, feche o painel. As alterações são guardadas automaticamente.

7. Adicione uma associação de aresta da tarefa Mapear para Oracle ao conector Obter dados da Oracle.

Recupere os detalhes do cliente da Oracle

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

1. No editor de integração, clique em Tasks para apresentar uma lista de tarefas disponíveis.
2. Clique e coloque o elemento Mapeamento de dados no editor de integração.
3. Clique no elemento Mapeamento de dados no criador para ver o painel de configuração da tarefa.
4. Clique em e mude o nome da tarefa Mapeamento de dados para 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)—com a variável de integração customer_record.

   Quando o mapeamento estiver concluído, feche o painel. As alterações são guardadas automaticamente.

7. Adicione uma ligação de limite do conetor Obter dados da Oracle à tarefa Obter dados da Oracle.

Adicione uma condição limite

Uma condição limite permite-lhe especificar as condições que têm de ser cumpridas para que o controlo de uma integração seja transmitido à tarefa ligada pelo limite. Agora que adicionou e configurou as tarefas necessárias, pode adicionar uma condição de limite para definir o fluxo da integração.

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

1. Adicione uma ligação de aresta do acionador API à tarefa Mapear para MySQL com a seguinte condição de aresta:

     $location$ = "US"

2. Adicione outra associação de aresta do acionador da API à tarefa Mapear para o Oracle com a seguinte condição de aresta:

     $location$ = "APAC"

Fluxo de integração de amostra

A figura seguinte mostra um exemplo de esquema da integração criada com este tutorial.



Publicar integração

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

Após publicar com êxito a integração, pode ver e inspecionar os registos de execução da integração publicada. Para ver os registos, clique em Ver registos de execução desta integração. É apresentada a página Registos de execução.

Teste a integração

Teste a integração a partir do editor de integrações

Para testar a integração a partir do editor de integração, siga estes passos:

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

   É apresentado o painel Test Integration (Testar integração).

2. É-lhe pedido que introduza os valores de teste para as variáveis de entrada da integração. Para este teste, faça o seguinte:
   • customer_id: introduza 1.
   • location: introduza APAC.
3. Clique em Testar integração.

A integração é executada com êxito e é apresentado o seguinte valor do cliente:

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

Para mais informações sobre os testes, consulte o artigo Teste e publique integrações.

Teste através de uma chamada da API REST

Agora que a integração está publicada e em execução, pode invocá-la através da seguinte chamada REST POST:

URL:

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

Corpo do pedido:

{"trigger_id":"api_trigger/api_fulfilment_API_1"}

Exemplo: fazer um pedido de API com entradas personalizadas

Nota: o exemplo seguinte usa curl, que normalmente vem pré-instalado para os sistemas operativos Linux e macOS. Se não tiver o curl, pode transferi-lo na curl página de lançamentos e transferências.

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 devolve a resposta de execução da integração que contém o seguinte JSON:

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

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, anule a publicação da integração e elimine as associações criadas no Integration Connectors.

• Para anular a publicação desta integração, clique em Anular publicação na barra de ferramentas do editor de integração. Consulte o artigo Elimine integrações para mais informações.
• Para obter informações sobre como eliminar uma associação, consulte o artigo Faça a gestão dos conetores.