Integração com a Apigee e conexão do MySQL

Neste tutorial, você verá como se conectar a uma instância de banco de dados MySQL usando uma integração de exemplo e executar as operações List, Get, Create, Update e Delete em uma tabela de banco de dados MySQL.

Antes de começar

Verifique se você tem acesso à integração da Apigee.
Selecione o projeto do Google Cloud e realize as seguintes tarefas:
- Conceda os seguintes papéis à conta de serviço que você quer usar para criar a conexão:
  - roles/secretmanager.viewer
  - roles/secretmanager.secretAccessor
- Ative os seguintes serviços:
  - secretmanager.googleapis.com (API Secret Manager)
  - connectors.googleapis.com (API Connectors)
  Se esses serviços não tiverem sido ativados para seu projeto anteriormente, você receberá uma solicitação para ativá-los ao criar a conexão.
Verifique se você tem acesso a um servidor MySQL que pode ser usado para criar um banco de dados. Para acessar uma lista de todos os conectores e as versões compatíveis, consulte a Referência do conector.

Crie um banco de dados e uma tabela no MySQL

Execute os seguintes comandos em um sistema que tem um cliente MySQL instalado:

Conecte-se ao servidor MySQL:
```
mysql --host=MYSQL_HOSTNAME_OR_IP_ADDRESS --port=PORT_NUMBER -uUSERNAME -pPASSWORD
```
Substitua o seguinte:
- MYSQL_HOSTNAME_OR_IP_ADDRESS pelo nome ou endereço IP do seu servidor MySQL.
- PORT_NUMBER pelo número da porta do seu servidor MySQL.
- USERNAME pelo nome de usuário do seu servidor MySQL.
- PASSWORD: pela senha do usuário do seu servidor MySQL.
Crie um banco de dados MySQL:
```
CREATE DATABASE tutorialDB;
```

Crie uma tabela:

CREATE TABLE EMPLOYEE
  (
  employee_id int auto_increment primary key,
  employee_first_name varchar(500) NOT null,
  employee_last_name varchar(500) NOT null,
  employee_emailID varchar(500)
  );

Adicione linhas à tabela EMPLOYEE que você criou:

INSERT INTO EMPLOYEE (employee_first_name,employee_last_name,employee_emailID) values ("Peter","Dilliard","test-01@test.com");
INSERT INTO EMPLOYEE (employee_first_name,employee_last_name,employee_emailID) values ("Meaghan","Webb","test-02@test.com");

Verifique se a tabela foi criada e se as linhas foram adicionadas:

SELECT * FROM EMPLOYEE;

As linhas da tabela a seguir serão exibidas:

+-------------+---------------------+--------------------+------------------+
| employee_id | employee_first_name | employee_last_name | employee_emailID |
+-------------+---------------------+--------------------+------------------+
|           1 | Peter               | Dilliard           | test-01@test.com |
|           2 | Meaghan             | Webb               | test-02@test.com |
+-------------+---------------------+--------------------+------------------+

Criar uma conexão do MySQL

Para permitir que uma integração se conecte ao seu banco de dados MySQL, crie uma nova conexão com o banco de dados MySQL:

Clique em + CRIAR NOVO para abrir a página Criar conexão.
Na seção Local, escolha o local da conexão.
1. Na lista Região, selecione a região em que você quer criar a conexão.
  Para conferir a lista de todas as regiões com suporte, consulte Locais.
2. Clique em Próxima.
Na seção Detalhes da conexão, insira os seguintes detalhes:
1. Na lista Conector, selecione MySQL (pré-lançamento).
2. Na lista Versão do conector, selecione a versão.
3. No campo Nome da conexão, insira um nome para a instância de conexão.
  Os nomes de conexão precisam atender aos seguintes critérios:
  - Use letras, números ou hifens.
  - As letras precisam ser minúsculas.
  - Os nomes precisam começar com uma letra e terminar com uma letra ou um número.
  - Os nomes não podem exceder 63 caracteres.
4. Opcional: no campo Descrição, adicione uma descrição da instância de conexão.
5. Opcional: ative o Cloud Logging.
6. Na lista Conta de serviço, selecione uma conta que tenha os papéis necessários.
7. No campo Nome do banco de dados, insira o nome do banco de dados MySQL.
8. Opcionalmente, defina as Configurações do nó de conexão:
  - Número mínimo de nós: digite o número mínimo de nós de conexão.
  - Número máximo de nós: digite o número máximo de nós de conexão.
  Um nó é uma unidade (ou réplica) de uma conexão que processa transações. Mais nós são necessários para processar mais transações para uma conexão e, por outro lado, menos nós são necessários para processar menos transações. Para entender como os nós afetam os preços do conector, consulte Preços dos nós de conexão. Se você não inserir qualquer valor, por padrão, os nós mínimos serão definidos como 2 (para melhor disponibilidade) e os nós máximos serão definidos como 50.
9. Usar proxy: marque esta caixa de seleção para configurar um servidor proxy para a conexão e defina os seguintes valores:
10. Opcional: para adicionar um rótulo à conexão, clique em + Adicionar rótulo.
11. Clique em Próxima.
12. Na seção Destinos, insira detalhes do host remoto (sistema de back-end) a que você quer se conectar.
  - Na lista Tipo de destino, selecione um endereço de host.
    1. No campo Endereço do host, especifique o nome do host ou o endereço IP do destino.
      1. Se você quiser estabelecer uma conexão privada com seus sistemas de back-end, siga estas etapas:
        
        Crie um anexo do serviço PSC.
        
        Crie um anexo de endpoint e insira os detalhes dele no campo Endereço do host.
      2. Para estabelecer uma conexão pública com os sistemas de back-end com mais segurança, considere configurar endereços IP de saída estáticos para suas conexões e configure as regras de firewall para autorizar apenas os endereços IP estáticos específicos.
    Para inserir outros destinos, clique em + Adicionar destino.
  - Clique em Próxima.
13. Na seção Autenticação, é possível fornecer as credenciais:
  - No campo Nome de usuário, digite o nome de usuário do MySQL para a conexão.
  - No campo Senha, insira o secret do Secret Manager que contém a senha associada ao nome de usuário do MySQL.
    - Se você tiver criado um secret anteriormente e não estiver disponível na lista, selecione Inserir secret manualmente. Na caixa de diálogo Adicionar um secret por ID do recurso, copie e cole o ID do recurso do Gerenciador de secrets.
      - Para usar a versão mais recente, copie e cole o ID do recurso do secret pai, no formato: "projects/project-number/secrets/secret-name"
      - Para selecionar uma versão específica, copie e cole o código do recurso para essa versão específica, no formato "projects/project-number/secrets/secret-name/versions/1"
      Para adicionar o secret, clique em Adicionar secret.
    - Se você não tiver criado um secret para uso com o MySQL, clique em Criar novo secret. Na caixa de diálogo Criar secret, insira os seguintes detalhes:
      - No campo Nome, insira o nome do secret.
      - No campo Valor do secret, insira o conteúdo do secret ou faça upload de um arquivo que o contenha.
      - Clique em Criar secret.
  - Na lista Versão do secret, selecione a versão do secret Senha na lista de versões disponíveis no menu suspenso.
  - Clique em Próxima.
Na seção Revisão, revise os detalhes de conexão e autenticação.
Clique em Criar.

Configurar a autenticação

Digite os detalhes com base na autenticação que você quer usar.

Nome de usuário e senha
- Nome de usuário: o nome de usuário do MySQL a ser usado para a conexão.
- Senha: o Secret do Secret Manager que contém a senha associada ao nome de usuário do MySQL.

Configurar uma integração para usar a conexão do MySQL

Para usar a conexão MySQL que você criou em uma integração, execute as seguintes tarefas:

Criar uma nova integração.
Adicionar e configurar um gatilho de API.
Adicionar e configurar uma tarefa dos conectores.
Conectar o elemento de gatilho de API ao elemento de tarefa dos conectores.

Criar uma nova integração

Na IU da Apigee, selecione sua organização da Apigee.
Clique em Desenvolver > Integrações.
Clique em CRIAR INTEGRAÇÃO.
No campo Nome da integração, insira um nome para sua integração.

Opcional: no campo Descrição, insira uma descrição.
Na lista Região, selecione uma região para a integração. A lista Regiões lista apenas as regiões provisionadas no seu projeto do Google Cloud. Para provisionar uma nova região, clique em Ativar região. Para informações sobre como provisionar novas regiões, consulte Ativar nova região.
Para abrir o editor de integração, clique em Criar.

Adicionar e configurar um gatilho de API

Depois de criar uma nova integração, é possível adicionar e configurar um gatilho da API para a integração. Para fazer isso, siga estas etapas:

Na barra de ferramentas do editor de integração, clique em Gatilhos para exibir uma lista de gatilhos disponíveis.
Arraste o elemento API para o editor de integração.

Adicionar e configurar uma tarefa do Connectors

Para configurar uma tarefa de Conectores e listar todas as entidades na tabela employee, siga estas etapas:

Na barra de ferramentas do editor de integração, clique em Tarefas para mostrar a lista de tarefas disponíveis.
Arraste o elemento Connectors para o editor de integração.
Clique no elemento de tarefa dos Conectores no designer para abrir o painel Conectores.
No painel Conectores, clique em Configurar conector.
Na caixa de diálogo Editor de tarefas do conector exibida, siga estas etapas:
1. Na lista Região, selecione a região da conexão em que você criou a conexão MySQL.
2. Na lista Conexão, selecione a conexão do MySQL que você criou e clique em Avançar.
3. Na seção Tipo, selecione Entidades e clique em Avançar.
4. Na lista Entidade, selecione funcionário.
5. Na lista Operação, selecione Lista e clique em Avançar.
6. Para concluir a configuração da conexão e fechar a caixa de diálogo, clique em Concluído.

Conectar o elemento acionador de API ao elemento de tarefa dos conectores

Em seguida, adicione uma conexão de borda para conectar o acionador da API à tarefa "Conectores". Uma borda é a conexão entre dois elementos em uma integração. Para informações sobre conexões e condições de conexão, consulte Conexões.

Para adicionar a conexão de borda, siga estas etapas:

Na parte de baixo do elemento "Gatilho da API", clique no ponto de controle Ramificação.
Arraste e solte a conexão de borda no ponto de controle Mesclar na parte superior do elemento de tarefa dos conectores.

Testar a integração

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

Na barra de ferramentas do editor de integração, clique em Testar.
Opcional: altere o valor Prazo de execução (em minutos) e clique em Testar integração.
Quando a integração for concluída, a caixa de diálogo Testar integração exibirá a mensagem Execução de integração concluída. Para visualizar os registros, clique em Visualizar registros.

Expanda a seção Parâmetros de resposta. Em Payload de saída do conector, a seguinte saída é exibida:

[ {
    "employee_id": 1.0,
    "employee_first_name": "Peter",
    "employee_last_name": "Dilliard",
    "employee_emailID": "test-01@test.com"
  },
  {
    "employee_id": 2.0,
    "employee_first_name": "Meaghan",
    "employee_last_name": "Webb",
    "employee_emailID": "test-02@test.com"
  } ]

Realizar outras operações na tabela do banco de dados MySQL

Ao configurar uma tarefa do Connectors na sua integração, você pode selecionar qualquer uma das seguintes operações:

Lista
Get
Criar
Atualizar
Excluir

Você já usou a operação de lista para conferir todas as linhas na tabela employee. Nas seções a seguir deste tutorial, você usará as operações Get, Create, Update e Delete para adicionar, modificar ou remover linhas da tabela employee.

Recuperar uma linha de uma tabela

Se você souber o ID da entidade (ou chave primária) da linha que quer buscar, forneça esse valor como entrada a uma operação Get na integração. Os detalhes retornados pela operação Get são semelhantes aos detalhes retornados pela operação List. No entanto, enquanto a operação de lista busca detalhes de todas as linhas da tabela que correspondem à consulta especificada, a operação Get busca detalhes apenas da linha da tabela que corresponde ao ID da entidade especificada.

A operação "List" retorna por padrão todas as linhas na tabela, mas a operação "Get" exige um ID de entidade como parâmetro de pesquisa. Portanto, para usar a operação Get, é necessário saber o ID da entidade da linha que você quer buscar ou fornecer um valor padrão para o ID da entidade.

Para conferir detalhes de uma linha especificada, siga estas etapas para configurar a tarefa Connectors criada anteriormente:

No editor de integração, clique no elemento de tarefa dos conectores para acessar o painel de configuração Conectores.
No painel de configuração Conectores, clique em Configurar conector. Na caixa de diálogo Editor de tarefas do conector que aparece, siga estas etapas:
1. Na seção Definir entidades/ação, na lista Operações, selecione Receber.
2. Clique em Concluído.
No painel de configuração Conectores, expanda a seção Entrada de tarefas. Em seguida, siga estas etapas:
1. Clique no ID da entidade.
2. Na caixa de diálogo Editar variável que aparece, selecione Entrada para integração.
3. Clique em Salvar.
Na barra de ferramentas do editor de integração, clique em Testar.
Opcional: altere o valor de Prazo de execução (em minutos).
Digite o ID da entidade que você quer buscar detalhes. Por exemplo, 2.
Clique em Testar integração.
Quando a integração for concluída, a caixa de diálogo Testar integração exibirá a mensagem Execução de integração concluída. Para visualizar os registros, clique em Visualizar registros.

Expanda a seção Parâmetros de resposta. Em Payload de saída do conector, a seguinte saída é exibida:

[ {
    "employee_id": 2.0,
    "employee_first_name": "Meaghan",
    "employee_last_name": "Webb",
    "employee_emailID": "test-02@test.com"
  } ]

Verifique se as informações mostradas aqui correspondem aos dados na linha correspondente da sua tabela MySQL. Para conferir essas informações na tabela do MySQL, execute o seguinte comando no cliente MySQL:

SELECT * FROM employee WHERE employee_id=2;

A linha da tabela a seguir será exibida:

+-------------+---------------------+--------------------+------------------+
| employee_id | employee_first_name | employee_last_name | employee_emailID |
+-------------+---------------------+--------------------+------------------+
|           2 | Meaghan             | Webb               | test-02@test.com |
+-------------+---------------------+--------------------+------------------+

Adicionar uma linha a uma tabela

Com a operação de criação, você pode adicionar uma linha em uma tabela. Ao usar a operação de criação, você precisa fornecer todos os valores da entidade no payload de entrada do conector.

Para adicionar uma linha usando a operação de criação, siga as etapas a seguir para configurar a tarefa Conectores, criada anteriormente:

No editor de integração, clique no elemento de tarefa dos conectores para acessar o painel de configuração Conectores.
No painel de configuração Conectores, clique em Configurar conector. Na caixa de diálogo Editor de tarefas do conector que aparece, siga estas etapas:
1. Na seção Definir entidades/ação, na lista Operações, selecione Criar.
2. Clique em Concluído.
No painel de configuração Conectores, expanda a seção Entrada de tarefas. Em seguida, siga estas etapas:
1. Clique no ID da entidade.
2. Na caixa de diálogo Editar variável que aparece, selecione Entrada para integração.
3. Clique em Salvar.
Na barra de ferramentas do editor de integração, clique em Testar.
Opcional: altere o valor de Prazo de execução (em minutos).
Digite os detalhes da entidade que você quer criar. Por exemplo, para adicionar um novo funcionário na tabela employee, digite o seguinte JSON:
```
{
  "employee_first_name": "Mary",
  "employee_last_name": "Smith",
  "employee_emailID": "test-03@test.com"
}
```
Observação: não especifique a chave primária, employee_id, porque ela é um valor somente leitura gerado quando a linha é adicionada à tabela.
Clique em Testar integração.
Quando a integração for concluída, a caixa de diálogo Testar integração exibirá a mensagem Execução de integração concluída. Para visualizar os registros, clique em Visualizar registros.
Expanda a seção Parâmetros de resposta. Em Payload de saída do conector, a seguinte saída é exibida:
```
{
  "employee_first_name": "Mary",
  "employee_last_name": "Smith",
  "employee_emailID": "test-03@test.com"
}
```
Em Payload de saída do conector, o ID da entidade é exibido como saída:
```
{
  "employee_id": 3.0
}
```

Você pode verificar se a linha foi adicionada à tabela do MySQL. Para conferir essas informações na tabela do MySQL, execute o seguinte comando no cliente MySQL:

SELECT * FROM employee;

As linhas da tabela a seguir serão exibidas:

+-------------+---------------------+--------------------+------------------+
| employee_id | employee_first_name | employee_last_name | employee_emailID |
+-------------+---------------------+--------------------+------------------+
|           1 | Peter               | Dilliard           | test-01@test.com |
|           2 | Meaghan             | Webb               | test-02@test.com |
|           3 | Mary                | Smith              | test-03@test.com |
+-------------+---------------------+--------------------+------------------+

Atualizar uma linha em uma tabela

Use a operação de atualização para fazer mudanças nos valores de uma linha da tabela. Por exemplo, é possível usar essa operação para atualizar o ID de e-mail de um funcionário na tabela employee. Para especificar a entidade que você quer atualizar, forneça o ID da entidade usado na operação Get. Também é possível usar o parâmetro Filtro de cláusula para transmitir valores em que filtrar as linhas da tabela. Isso é útil se você quer fazer a mesma mudança em várias linhas com base em critérios de pesquisa específicos.

Para atualizar uma linha da tabela, siga estas etapas para configurar a tarefa Conectores, criada anteriormente:

No editor de integração, clique no elemento de tarefa dos conectores para acessar o painel de configuração Conectores.
No painel de configuração Conectores, clique em Configurar conector. Na caixa de diálogo Editor de tarefas do conector que aparece, siga estas etapas:
1. Na seção Definir entidades/ação, na lista Operações, selecione Atualizar.
2. Clique em Concluído.
No painel de configuração Conectores, expanda a seção Entrada de tarefas. Em seguida, siga estas etapas:
1. Clique em Cláusula de filtro.
2. Na caixa de diálogo Editar variável que aparece, selecione Entrada para integração.
3. Clique em Salvar.
Na barra de ferramentas do editor de integração, clique em Testar.
Opcional: altere o valor de Prazo de execução (em minutos).
Insira os critérios do filtro. Por exemplo, para encontrar um funcionário com o código de e-mail test-03@test.com, digite:
```
employee_emailID="test-03@test.com"
```
Observação: se você tiver várias linhas de tabela que correspondam aos critérios de filtro, a atualização especificada na próxima etapa será feita em todas as linhas correspondentes.
Insira os valores que você quer atualizar. Por exemplo, para atualizar o ID de e-mail de todos os funcionários na tabela employee cujo ID de e-mail atual corresponde à cláusula de filtro test-03@test.com, digite o seguinte JSON:
```
{
  "employee_emailID": "msmith@test.com"
}
```
Observação: não é necessário especificar valores para todas as colunas na tabela. Insira os valores que você quer atualizar. Os outros valores não são modificados.
Clique em Testar integração.
Quando a integração for concluída, a caixa de diálogo Testar integração exibirá a mensagem Execução de integração concluída.
Para validar se a entidade foi atualizada, use a operação Get para conferir os detalhes da entidade especificada.

Você pode verificar se a linha está atualizada na tabela do MySQL. Para conferir essas informações na tabela do MySQL, execute o seguinte comando no cliente MySQL:

SELECT * FROM employee;

As linhas da tabela a seguir serão exibidas:

+-------------+---------------------+--------------------+------------------+
| employee_id | employee_first_name | employee_last_name | employee_emailID |
+-------------+---------------------+--------------------+------------------+
|           1 | Peter               | Dilliard           | test-01@test.com |
|           2 | Meaghan             | Webb               | test-02@test.com |
|           3 | Mary                | Smith              | msmith@test.com  |
+-------------+---------------------+--------------------+------------------+

Excluir uma linha de uma tabela

Use a operação de exclusão para excluir uma ou mais linhas da tabela. Informe o ID da entidade ou use a cláusula de filtro para especificar as linhas que você quer excluir. Lembre-se de que, se você usar a cláusula de filtro para especificar os critérios das linhas que quer excluir, será possível excluir várias linhas que correspondam ao filtro especificado. Se você quiser excluir apenas uma linha específica, use o ID da entidade.

Para excluir uma linha da tabela usando o código da entidade, siga as etapas abaixo para configurar a tarefa Conectores que você criou anteriormente:

No editor de integração, clique no elemento de tarefa dos conectores para acessar o painel de configuração Conectores.
No painel de configuração Conectores, clique em Configurar conector. Na caixa de diálogo Editor de tarefas do conector que aparece, siga estas etapas:
1. Na seção Definir entidades/ação, na lista Operações, selecione Receber.
2. Clique em Concluído.
No painel de configuração Conectores, expanda a seção Entrada de tarefas. Em seguida, siga estas etapas:
1. Clique no ID da entidade.
2. Na caixa de diálogo Editar variável que aparece, selecione Entrada para integração.
3. Clique em Salvar.
Na barra de ferramentas do editor de integração, clique em Testar.
Opcional: altere o valor de Prazo de execução (em minutos).
Digite o ID da entidade que você quer buscar detalhes. Por exemplo, 2.
Clique em Testar integração.
Quando a integração for concluída, a caixa de diálogo Testar integração exibirá a mensagem Execução de integração concluída.
Para validar se a linha da tabela foi excluída, use a operação Get para conferir os detalhes da linha que você excluiu. Isso retornará um erro para o ID da entidade especificada.

Também é possível usar a operação List e, opcionalmente, fornecer uma cláusula de filtro para as linhas da tabela que você excluiu. Isso retornará a lista de linhas restantes, que pode ser uma lista vazia.

Por exemplo, se você excluiu a linha da tabela com o ID da entidade 3 e depois especifica a cláusula de filtro employee_emailID="msmith@test.com" ou o ID da entidade 3 para a operação List, os parâmetros de resposta nos registros exibem [].

Você pode verificar se a linha foi excluída da tabela do MySQL. Para verificar isso na tabela MySQL, execute o seguinte comando no seu cliente MySQL:

SELECT * FROM employee;

As linhas da tabela a seguir serão exibidas:

+-------------+---------------------+--------------------+------------------+
| employee_id | employee_first_name | employee_last_name | employee_emailID |
+-------------+---------------------+--------------------+------------------+
|           1 | Peter               | Dilliard           | test-01@test.com |
|           2 | Meaghan             | Webb               | test-02@test.com |
+-------------+---------------------+--------------------+------------------+

A seguir

Tente criar integrações com outros conectores. Para conferir a lista de todos os conectores compatíveis, consulte a Referência de conectores.