Cumprimento de solicitações de API

Este tutorial descreve um caso de uso de como usar Application Integration para encaminhar 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 da localização da solicitação de API, a integração recupera os detalhes do cliente de um banco de dados MySQL ou Oracle.

Diagrama de atendimento da API Diagrama de atendimento da API

Objetivos

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

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

Custos

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

As instruções deste tutorial foram criadas para manter o 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. 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.

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

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Create a service account:

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

      Go to Create service account
    2. Select your project.

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

    4. Click Create and continue.

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

    6. Click Continue.

    7. Click Done to finish creating the service account.

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

    Go to project selector

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Create a service account:

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

      Go to Create service account
    2. Select your project.

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

    4. Click Create and continue.

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

    6. Click Continue.

    7. Click Done to finish creating the service account.

Preparar 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. Este tutorial usa 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          | test-01@test.com   | New York         |
  |           2 | Dana          | test-02@test.com   | Seattle          |
  +-------------+---------------+--------------------+------------------+

Para informações 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. Este tutorial usa 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          | test-01@test.com   | Delhi            |
  |           2 | Hao           | test-02@test.com   | Beijing          |
  +-------------+---------------+--------------------+------------------+

Para informações sobre como criar e usar um banco de dados Oracle, consulte a documentação da Oracle.

Configurar conexões

Para este tutorial, você precisa configurar as seguintes conexões em Conectores de integração:

Conexão do MySQL
Configure uma conexão do MySQL no Integration Connectors para receber as entidades de tabelas Customer. Para informações sobre como configurar um conector do MySQL, consulte Conector do MySQL.
Conexão com o Oracle DB
Configure uma conexão do Oracle DB no Integration Connectors para receber as entidades de tabelas Customer. Para informações sobre como configurar 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. Clique em Integrações no menu de navegação à esquerda para abrir a página Integrações.
  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 compatíveis.
    4. Clique em Criar para abrir o editor de integração.

Configurar um gatilho de integração

Depois de criar a integração, adicione e configure um gatilho que a invoque para um evento identificado.

Neste tutorial, um acionador de API é usado para invocar a integração a 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.

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

    3. 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 (painel "Alternar") na barra de navegação do designer para abrir o painel Variáveis.
  2. Clique em + Criar e crie as seguintes variáveis de integração:
    Nome da variável Tipo de dado 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 de clientes do banco de dados MySQL

Se a solicitação da API de entrada for do local US, faça o seguinte para recuperar dados do cliente do banco de dados MySQL.

Conectar-se ao banco de dados MySQL

Siga estas etapas para adicionar e configurar uma tarefa do Connectors e recuperar os detalhes dos clientes da tabela Customers do MySQL:

  1. No editor de integração, clique em Tarefas para mostrar uma lista de 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 ver o painel de configuração da tarefa Conectores.
  4. Clique em e renomeie o marcador Conectores para 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 Acessar como a Operação.
    6. Clique em Concluído para concluir a configuração da conexão e feche o painel.

Mapear o ID do cliente para o conector MySQL

Uma tarefa de Mapeamento de dados é usada para mapear o ID do cliente ao 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 mostrar uma lista de 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 conferir o painel de configuração da tarefa.
  4. Clique em e renomeie a tarefa Mapeamento de dados para 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 mapeamento de variáveis, consulte Adicionar um mapeamento.

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

    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 mostrar uma lista de tarefas disponíveis.
  2. Clique e posicione o elemento Mapeamento de dados no editor de integração.
  3. Clique no elemento Mapeamento de dados no designer para conferir o painel de configuração da tarefa.
  4. Clique em e renomeie a 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 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 de clientes do banco de dados Oracle

Se a solicitação de API de entrada for do local APAC, faça o seguinte para recuperar dados do cliente do banco de dados Oracle.

Conectar-se ao banco de dados Oracle

Siga estas etapas para adicionar e configurar uma tarefa de Conectores para recuperar os detalhes dos clientes na tabela Customers do Oracle:

  1. No editor de integração, clique em Tarefas para mostrar uma lista de 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 ver o painel de configuração da tarefa Conectores.
  4. Clique em e renomeie o marcador Conectores para 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 Acessar como a Operação.
    6. Clique em Concluído para concluir a configuração da conexão e feche o painel.

Mapear o ID do 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 mostrar uma lista de 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 conferir o painel de configuração da tarefa.
  4. Clique em e renomeie a tarefa Mapeamento de dados para Map to Oracle.
  5. Clique em Abrir editor de mapeamento de dados.
  6. Mapeie a variável de gatilho —customer_id— de integração com a variável de entrada do conector gerada automaticamente —entityId(Fetch Oracle Data)—.

    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 Oracle

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

  1. No editor de integração, clique em Tarefas para mostrar uma lista de tarefas disponíveis.
  2. Clique e posicione o elemento Mapeamento de dados no editor de integração.
  3. Clique no elemento Mapeamento de dados no designer para conferir o painel de configuração da tarefa.
  4. Clique em e renomeie a 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)—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 Receber dados do Oracle.

Adicionar condição de borda

Com uma condição de borda, é possível especificar as condições que precisam ser atendidas para que o controle de uma integração seja transmitido para a tarefa conectada pela borda. Agora que você adicionou e configurou as tarefas necessárias, é possível adicionar uma condição de borda para definir o fluxo da integração.

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

  1. Adicione uma conexão de borda do gatilho API à tarefa Mapear para MySQL com a seguinte condição de borda: 
      $location$ = "US"
  2. Adicione outra conexão de borda do acionador 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.

Imagem de exemplo mostrando o fluxo de integração Imagem de exemplo mostrando o fluxo de integração

Publicar integraçã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 ver os registros, clique em imagem mostrando o ícone de registros de execuçãoExibir 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 no editor de integração, siga estas etapas:

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

    O painel Test Integration é exibido.

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

A integração é executada com sucesso e o seguinte valor do cliente é exibido:

{ 
  "CUSTOMER_ID": 1,
  "CUSTOMER_NAME": "Amal"
  "CUSTOMER_EMAILID": "test-01@test.com "
  "CUSTOMER_CITY": "Delhi"
}

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

Testar usando uma chamada de API REST

Agora que a integração está publicada e em execução, é possível invocá-la usando a seguinte chamada POST REST:

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

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 com o seguinte JSON: 

  { 
    "CUSTOMER_ID": 2,
    "CUSTOMER_NAME": "Dana"
    "CUSTOMER_EMAILID": "test-02@test.com "
    "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 no Integration Connectors.

  • Para cancelar a publicação dessa 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 saber como excluir uma conexão, consulte Gerenciar conectores.