Consulte os conectores compatíveis com a Application Integration.

Inserir dados no BigQuery usando uma tarefa Para cada paralelo

Neste tutorial, você vai criar uma Application Integration e uma subintegração para processar uma série de registros. Para cada registro, a integração principal invoca de maneira assíncrona a subintegração, que pega os dados de cada registro e os insere como uma linha em uma tabela de um conjunto de dados do BigQuery.

Neste tutorial, você concluirá as seguintes tarefas:

Configurar uma conexão do BigQuery
Configurar uma subintegração
Configurar a integração principal
Testar sua integração

Antes de começar

Verifique se você tem acesso à integração da Apigee.
Faça o seguinte no seu projeto do Google Cloud:
- Conceda os seguintes papéis à conta de serviço que você quer usar para criar a conexão:
  - roles/bigquery.dataEditor
  - roles/bigquery.readSessionUser
  - 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 no projeto anteriormente, será solicitado que você os ative ao criar a conexão na página Criar conexão.

Configurar uma conexão do BigQuery

Comece criando o conjunto de dados e a tabela do BigQuery para usar neste tutorial. Depois de criar o conjunto de dados e a tabela, crie uma conexão do BigQuery. Você usará essa conexão em uma integração mais adiante neste tutorial.

Configurar um conjunto de dados e uma tabela do BigQuery

Para configurar o conjunto de dados e a tabela do BigQuery, siga estas etapas:

Na página Console do Cloud, selecione seu projeto do Google Cloud.
Para iniciar uma sessão do Cloud Shell no console do Google Cloud, clique no ícone Ativar o Cloud Shell no console do Cloud. Isso inicia uma sessão no painel inferior do Cloud Console.
Para ativar as APIs do BigQuery, digite os seguintes comandos no terminal do Cloud Shell:
```
export PROJECT_ID=project_id
export REGION=region
gcloud services enable --project "${PROJECT_ID}" \
    bigquery.googleapis.com \
    bigquerystorage.googleapis.com
```
Nesse comando, substitua:
- project_id pelo ID do projeto do Google Cloud.
- region pela região que você quer usar para criar o conjunto de dados do BigQuery.
Para criar um conjunto de dados do BigQuery com o nome bq_tutorial, digite o seguinte comando no terminal do Cloud Shell:
```
      bq  --project_id ${PROJECT_ID} --location ${REGION} mk bq_tutorial
    
```

Para criar uma tabela do BigQuery com o nome tutorial, digite o seguinte comando no terminal do Cloud Shell:

      bq --project_id ${PROJECT_ID} \
        query  \
        --nouse_legacy_sql \
      'create table bq_tutorial.tutorial (
      unique_key STRING NOT NULL,
      created_date STRING,
      closed_date STRING,
      agency STRING,
      agency_name STRING,
      complaint_type STRING,
      descriptor STRING,
      location_type STRING,
      incident_zip STRING,
      incident_address STRING,
      street_name STRING,
      cross_street_1 STRING,
      cross_street_2 STRING,
      intersection_street_1 STRING,
      intersection_street_2 STRING,
      address_type STRING,
      city STRING,
      landmark STRING,
      facility_type STRING,
      status STRING,
      due_date STRING,
      resolution_action_updated_date STRING,
      community_board STRING,
      borough STRING,
      x_coordinate_state_plane STRING,
      y_coordinate_state_plane STRING,
      park_facility_name STRING,
      park_borough STRING,
      school_name STRING,
      school_number STRING,
      school_region STRING,
      school_code STRING,
      school_phone_number STRING,
      school_address STRING,
      school_city STRING,
      school_state STRING,
      school_zip STRING,
      school_not_found STRING,
      school_or_citywide_complaint STRING,
      vehicle_type STRING,
      taxi_company_borough STRING,
      taxi_pick_up_location STRING,
      bridge_highway_name STRING,
      bridge_highway_direction STRING,
      bridge_highway_segment STRING,
      road_ramp STRING,
      garage_lot_name STRING,
      ferry_direction STRING,
      ferry_terminal_name STRING,
      latitude STRING,
      longitude STRING,
      location STRING
      ) '

Verifique se a tabela do BigQuery foi criada.
1. Na página do console do Cloud, clique em Menu de navegação.
2. Na seção Analytics, clique em BigQuery.
3. Expanda seu projeto e confirme se o conjunto de dados bq_tutorial está listado.
4. Expanda o conjunto de dados bq_tutorial e confirme se a tabela tutorial está listada.
5. Clique na tabela de documentos para conferir o esquema.

Criar uma conexão do BigQuery

Em seguida, você vai criar uma conexão com o BigQuery. A conexão do BigQuery permite inserir, ler, atualizar e excluir linhas em uma tabela do BigQuery e usar a saída resultante em uma integração. Depois de criar a conexão do BigQuery, você usará essa conexão em uma integração posteriormente neste tutorial para adicionar linhas à tabela do BigQuery.

Para criar uma conexão do BigQuery, siga estas etapas:

Na página console do Cloud, selecione seu projeto do Google Cloud.
Abra a página de conexões.
Clique em + CRIAR NOVO para abrir a página Criar conexão.
Configure a conexão:
1. Na seção Criar conexão, faça o seguinte:
  - Conector: selecione BigQuery na lista suspensa de conectores disponíveis.
  - Versão do conector: selecione a versão mais recente do conector na lista suspensa de versões disponíveis.
  - No campo Nome da conexão, insira um nome para a instância de conexão Para este tutorial, acesse connector-bq-tutorial.
    Observação: os nomes de conexão precisam atender aos seguintes critérios:
    - Os nomes de conexões podem usar letras, números ou hifens.
    - As letras precisam ser minúsculas.
    - Os nomes das conexões precisam começar com uma letra e terminar com uma letra ou um número.
    - Os nomes das conexões não podem exceder 63 caracteres.
  - Se quiser, adicione uma Descrição da instância de conexão.
  - Conta de serviço: selecione uma conta de serviço que tenha os papéis necessários.
  - ID do projeto: insira o ID do projeto do Google Cloud em que os dados do BigQuery estão armazenados.
  - ID do conjunto de dados: insira o ID do conjunto de dados do BigQuery que você quer usar. Para este tutorial, insira bq_tutorial.
  - Outra opção é clicar em + ADICIONAR MARCADOR para adicionar um rótulo na forma de um par de chave-valor.
  - Clique em Próxima.
2. Local: selecione uma região em que a conexão será executada. Supported regions for connectors include:
  - Clique em Próxima.
3. Autenticação: a conexão do BigQuery não requer configuração de autenticação. Clique em Próximo.
4. Revisão: revise os detalhes de configuração das suas conexões. Nesta seção, os detalhes da conexão e os detalhes da autenticação da nova conexão são exibidos para sua revisão.
Clique em Criar.

Configurar uma subintegração

Neste tutorial, a subintegração recebe cada registro enviado pela integração principal e o insere como uma linha na tabela tutorial do conjunto de dados bq_tutorial.

Criar uma subintegração

Para criar a subintegração, siga estas etapas:

No console do Google Cloud, acesse a página Application Integration.
Acessar o Application Integration
No menu de navegação, clique em Integrações. A página Lista de integrações é exibida.
Clique em CRIAR INTEGRAÇÃO.
Na caixa de diálogo Criar integração, execute as ações a seguir:

Digite um nome, por exemplo, Process-each-record
Observação: os nomes de integração precisam atender aos seguintes requisitos:
- Os nomes precisam começar e terminar com letras ou números.
- Os nomes não podem conter espaços ou mais de um traço ou sublinhado em uma linha.
Opcionalmente, insira uma descrição. Por exemplo, digite um gatilho da API para processar cada registro (subintegração).
Selecione a região em que você quer criar a integração.

Clique em Criar para abrir o editor de integração.

Adicionar um gatilho de API

Para adicionar um gatilho de API à integração, faça o seguinte:

No designer de integração, selecione Adicionar uma tarefa/gatilho > Gatilhos para exibir uma lista de gatilhos disponíveis.
Arraste o elemento Gatilho da API para o designer de integração.

Adicionar uma tarefa de mapeamento de dados

Para adicionar uma tarefa de mapeamento de dados à integração, siga estas etapas:

Selecione + Adicionar uma tarefa/acionador > Tarefas no editor de integração para exibir a lista de tarefas disponíveis.
Arraste o elemento Mapeamento de dados para o designer de integração.

Configurar a conexão do BigQuery

Agora está tudo pronto para usar a conexão do BigQuery criada na subintegração. Para configurar a conexão do BigQuery nessa integração, siga estas etapas:

Selecione + Adicionar uma tarefa/acionador > Tarefas no editor de integração para exibir 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 conferir o painel de configuração da tarefa.
Clique no ícone de edição no painel direito e atualize o identificador para Inserir linha ao BigQuery.
Clique em Configurar tarefa.
A caixa de diálogo Configurar conector será exibida.
Na caixa de diálogo Configurar conector da tarefa, faça o seguinte:
1. Selecione a região da conexão em que você criou a conexão do BigQuery.
2. Selecione a conexão do BigQuery que você quer usar. Para este tutorial, selecione connector-bq-tutorial.
3. Depois que uma conexão é escolhida, a coluna Tipo é exibida. Selecione Entidades e depois tutorial na lista de entidades disponíveis.
4. Depois que um tipo é escolhido, a coluna Operação é exibida. Selecione Criar.
5. Clique em Concluído para concluir a configuração da conexão e feche o painel.

Conectar os elementos de integração

Em seguida, adicione conexões de borda para conectar o Gatilho da API à tarefa Mapeamento de dados e a tarefa Mapeamento de dados aos Conectores. Uma borda é a conexão entre dois elementos em uma integração. Para mais informações sobre as bordas e as condições das bordas, consulte Bordas.

Para adicionar as conexões de borda, siga estas etapas:

Clique no ponto de controle Ramificação na parte inferior do elemento Gatilho da API. Arraste e solte a conexão de borda no ponto de controle Mesclar na parte de cima do elemento Mapeamento de dados.
Clique no ponto de controle Ramificação na parte de baixo do elemento Mapeamento de dados. Arraste e solte a conexão de borda no ponto de controle Mesclar na parte superior do elemento de tarefa Conectores.

Configurar a tarefa "Mapeamento de dados"

Para configurar a tarefa de mapeamento de dados, siga estas etapas:

No designer de integração, clique na tarefa Mapeamento de dados para conferir o painel de configuração da tarefa.
Clique em Abrir editor de mapeamento de dados.
No Editor de mapeamento de dados, clique em Adicionar para incluir uma nova variável.

Na caixa de diálogo Criar variável, insira as seguintes informações:

Nome: digite registro.
Tipo de dado: selecione JSON.

Esquema: selecione Inferir de um payload JSON de amostra. Digite o seguinte payload JSON de amostra:

            {
              "unique_key":"304271",
              "created_date":"02/06/2007 12:00:00 AM",
              "closed_date":"03/01/2007 12:00:00 AM",
              "agency":"TLC",
              "agency_name":"Taxi and Limousine Commission",
              "complaint_type":"Taxi Complaint",
              "descriptor":"Driver Complaint",
              "location_type":"Street",
              "incident_zip":"10001",
              "incident_address":"",
              "street_name":"",
              "cross_street_1":"",
              "cross_street_2":"",
              "intersection_street_1":"WEST 29 STREET",
              "intersection_street_2":"7 AVENUE",
              "address_type":"INTERSECTION",
              "city":"NEW YORK",
              "landmark":"",
              "facility_type":"N/A",
              "status":"Closed",
              "due_date":"02/28/2007 12:00:00 AM",
              "resolution_action_updated_date":"03/01/2007 12:00:00 AM",
              "community_board":"05 MANHATTAN",
              "borough":"MANHATTAN",
              "x_coordinate_state_plane":"986215",
              "y_coordinate_state_plane":"211740",
              "park_facility_name":"",
              "park_borough":"MANHATTAN",
              "school_name":"",
              "school_number":"",
              "school_region":"",
              "school_code":"",
              "school_phone_number":"",
              "school_address":"",
              "school_city":"",
              "school_state":"",
              "school_zip":"",
              "school_not_found":"",
              "school_or_citywide_complaint":"",
              "vehicle_type":"",
              "taxi_company_borough":"",
              "taxi_pick_up_location":"Other",
              "bridge_highway_name":"",
              "bridge_highway_direction":"",
              "road_ramp":"",
              "bridge_highway_segment":"",
              "garage_lot_name":"",
              "ferry_direction":"",
              "ferry_terminal_name":"",
              "latitude":"40.74785373937869",
              "longitude":"-73.99290823133913",
              "location":"(40.74785373937869, -73.99290823133913)"
            }

Clique em Criar.
Quando a variável for criada, no Editor de mapeamento de dados, siga estas etapas:
- Arraste a nova variável registro para a coluna Saída.
- Arraste a variável connectorInputPayload para a coluna Saída.
Feche o Editor de mapeamento de dados para retornar ao editor de integração.

Publicar a subintegração

Para publicar a subintegração, clique em Publicar no editor de integração.

Configurar a integração principal

Nesta seção, você vai configurar a integração principal, que usa uma tarefa Para cada paralelo para processar cada registro. Em seguida, essa integração principal invoca a subintegração uma vez para cada registro.

Criar a integração principal

Para criar a integração principal, siga estas etapas:

No console do Google Cloud, acesse a página Application Integration.
Acessar o Application Integration
No menu de navegação, clique em Integrações. A página Lista de integrações é exibida.
Clique em CRIAR INTEGRAÇÃO.
Na caixa de diálogo Criar integração, execute as ações a seguir:

Digite um nome, por exemplo, process-records.
Observação: os nomes de integração precisam atender aos seguintes requisitos:
- Os nomes precisam começar e terminar com letras ou números.
- Os nomes não podem conter espaços ou mais de um traço ou sublinhado em uma linha.
Opcionalmente, insira uma descrição. Por exemplo, digite o Gatilho da API para processar registros (integração principal).
Selecione a região em que você quer criar a integração.

Clique em Criar para abrir o editor de integração.

Adicionar um gatilho de API

Para adicionar um gatilho de API à integração, faça o seguinte:

No designer de integração, selecione Adicionar uma tarefa/gatilho > Gatilhos para exibir uma lista de gatilhos disponíveis.
Arraste o elemento Gatilho da API para o designer de integração.

Adicionar uma tarefa Para cada paralelo

Para adicionar uma tarefa para cada paralelo na integração, siga estas etapas:

Selecione + Adicionar uma tarefa/acionador > Tarefas no editor de integração para exibir a lista de tarefas disponíveis.
Arraste o elemento Para cada paralelo até o designer de integração.

Conectar os elementos de integração

Em seguida, adicione uma conexão de borda para conectar o gatilho da API à tarefa Para cada paralelo.

Para adicionar a conexão de borda, clique no ponto de controle Fork na parte inferior do elemento API Trigger. Arraste e solte a conexão de borda no ponto de controle Mesclar na parte de cima do elemento da tarefa Para cada paralelo.

Configurar a tarefa "Para cada paralelo"

Para configurar a tarefa "Para cada paralelo", siga estas etapas:

No designer de integração, clique na tarefa Para cada paralelo para conferir o painel de configuração da tarefa.
Em Seleção de matriz > Lista para iteração, clique em Adicionar nova variável para adicionar uma nova variável.

Na caixa de diálogo Criar variável, insira as seguintes informações:

Nome:insira records.
Tipo de dado: selecione JSON.

Esquema: selecione Inferir de um payload JSON de amostra. Digite o seguinte payload JSON de amostra:

              [{
                "unique_key":"304271",
                "created_date":"02/06/2007 12:00:00 AM",
                "closed_date":"03/01/2007 12:00:00 AM",
                "agency":"TLC",
                "agency_name":"Taxi and Limousine Commission",
                "complaint_type":"Taxi Complaint",
                "descriptor":"Driver Complaint",
                "location_type":"Street",
                "incident_zip":"10001",
                "incident_address":"",
                "street_name":"",
                "cross_street_1":"",
                "cross_street_2":"",
                "intersection_street_1":"WEST 29 STREET",
                "intersection_street_2":"7 AVENUE",
                "address_type":"INTERSECTION",
                "city":"NEW YORK",
                "landmark":"",
                "facility_type":"N/A",
                "status":"Closed",
                "due_date":"02/28/2007 12:00:00 AM",
                "resolution_action_updated_date":"03/01/2007 12:00:00 AM",
                "community_board":"05 MANHATTAN",
                "borough":"MANHATTAN",
                "x_coordinate_state_plane":"986215",
                "y_coordinate_state_plane":"211740",
                "park_facility_name":"",
                "park_borough":"MANHATTAN",
                "school_name":"",
                "school_number":"",
                "school_region":"",
                "school_code":"",
                "school_phone_number":"",
                "school_address":"",
                "school_city":"",
                "school_state":"",
                "school_zip":"",
                "school_not_found":"",
                "school_or_citywide_complaint":"",
                "vehicle_type":"",
                "taxi_company_borough":"",
                "taxi_pick_up_location":"Other",
                "bridge_highway_name":"",
                "bridge_highway_direction":"",
                "road_ramp":"",
                "bridge_highway_segment":"",
                "garage_lot_name":"",
                "ferry_direction":"",
                "ferry_terminal_name":"",
                "latitude":"40.74785373937869",
                "longitude":"-73.99290823133913",
                "location":"(40.74785373937869, -73.99290823133913)"
              }]

Clique em Criar.
Na seção Sub-integration Details, insira as seguintes informações:
- ID do Gatilho da API: selecione o elemento do gatilho da API na subintegração. Por exemplo, selecione Process-each-record_API_1.
- Estratégia de execução: selecione ASYNC.
- Selecione Run a single integration.
Na seção Em cada execução, em Onde mapear elementos individuais da matriz, insira o nome da variável na tarefa de mapeamento de dados na subintegração. Nesse caso, digite registro. As variáveis de subintegração são listadas apenas para integrações publicadas. Se as variáveis não estiverem listadas, atualize a página. Pode levar algum tempo até que as variáveis fiquem visíveis após a publicação da subintegração.

Publicar a integração principal

Para publicar a integração principal, clique em Publicar no editor.

Testar sua integração

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

Faça o download dos dados de amostra para o Cloud Shell:
1. Para iniciar uma sessão do Cloud Shell no console do Google Cloud, clique no ícone Ativar o Cloud Shell no console do Cloud. Isso inicia uma sessão no painel inferior do Cloud Console.
2. Digite o seguinte comando no terminal do Cloud Shell:
```
wget https://raw.githubusercontent.com/GoogleCloudPlatform/application-integration-samples/main/assets/bq-sample-dataset.json
        
```
3. Para verificar se o download dos dados de amostra foi concluído, digite o seguinte comando no terminal do Cloud Shell:
```
ls -la bq-sample-dataset.json
```
  O arquivo salvo é listado no terminal do Cloud Shell.

Para selecionar três entradas aleatórias do conjunto de dados de amostra e armazená-las para serem transmitidas à integração, digite os seguintes comandos no terminal do Cloud Shell:

AUTH=$(gcloud auth print-access-token)
export SAMPLE_DOCS=$(jq $(r=$((RANDOM % 1000)) ; echo ".[$r:$((r + 3))]") < bq-sample-dataset.json | jq -Rs '.')

generate_post_data()
  {
    cat <<EOF
      {
        "triggerId": "api_trigger/process-records_API_1",
        "inputParameters":
          {
            "records":
              {
                "jsonValue": $SAMPLE_DOCS
              }
          }
      }
      EOF
  }

Para iniciar o teste, digite o seguinte comando no terminal do Cloud Shell:
```
curl -X POST \
  https://integrations.googleapis.com/v1/projects/project_id/locations/region/integrations/process-records:execute \
  -H "Authorization: Bearer $AUTH" \
  -H "Content-Type: application/json" \
  -d "$(generate_post_data)"
```
Nesse comando, substitua:
- project_id pelo ID do projeto do Google Cloud.
- region pela região em que você criou sua integração.
Esse comando invoca a integração principal e transmite as entradas do conjunto de dados de amostra para a integração principal. A integração principal passa cada entrada para a subintegração, que adiciona os dados como uma linha na tabela do BigQuery.
Para verificar se a tabela do BigQuery agora contém esses registros, siga estas etapas:
1. Na página do console do Cloud, clique em Menu de navegação.
2. Na seção Analytics, clique em BigQuery.
3. Expanda seu projeto e clique no conjunto de dados bq_tutorial.
4. Expanda o conjunto de dados bq_tutorial e clique na tabela tutorial.
5. Clique na guia Explorador de tabelas para conferir os registros inseridos.

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.