Consulte os conectores compatíveis com o Application Integration.

Ver a especificação OpenAPI da sua integração

Prévia — OpenAPI Specification

Este recurso está sujeitos aos "Termos das Soluções Pré-GA" na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis no estado em que se encontram e podem ter suporte limitado. Para mais informações, consulte as descrições das fases de lançamento.

Application Integration permite gerar e visualizar dinamicamente as especificações OpenAPI das suas integrações publicadas que estão configuradas com um ou mais gatilhos de API. Ao acessar a especificação OpenAPI da sua integração, você pode:

• Entenda os endpoints, métodos e estruturas de dados da API da sua integração.
• Permite um desenvolvimento e uma solução de problemas mais eficientes ao fornecer uma visão detalhada e centralizada da API da sua integração.
• Exponha suas APIs de integração e integre-se perfeitamente aos agentes de conversação. Consulte Criar agentes de conversação com a Application Integration.

O que é a especificação do OpenAPI?

A especificação OpenAPI (OAS, na sigla em inglês) é um formato padrão e independente de linguagem para descrever APIs RESTful. Normalmente escrita em formatos YAML ou JSON, a especificação OpenAPI apresenta uma descrição formal dos elementos da API, como URL base, caminhos e verbos, cabeçalhos, parâmetros de consulta, tipos de conteúdo, modelos de solicitação e resposta e muito mais. Para mais informações sobre a especificação OpenAPI, consulte Especificação OpenAPI.

Observação:o Application Integration só é compatível com a especificação OpenAPI versão 3.0.1.

Gerar e visualizar a especificação OpenAPI

É possível gerar e visualizar dinamicamente a especificação OpenAPI das suas integrações no editor de integração do console Google Cloud ou usando uma chamada de API.

Antes de começar

• Confirme se a integração está configurada com um ou mais gatilhos de API. Para informações sobre como configurar gatilhos de API, consulte Gatilhos de API.
• Publique a integração. Para informações sobre como publicar uma integração, consulte Testar e publicar integrações.

Ver especificação OpenAPI

Para conferir a especificação OpenAPI da sua integração, selecione uma das opções:

Console

Para conferir a especificação OpenAPI de uma integração específica, siga estas etapas:

1. Acesse a página Application Integration.

   Acessar o Application Integration

2. No menu de navegação, clique em Integrações.

   A página Integrações aparece, listando todas as integrações disponíveis no projeto Google Cloud .

3. Clique na integração para ver a especificação OpenAPI. Isso abre a integração no editor de integração.
4. Clique em (menu "Ações") na barra de ferramentas do editor de integração e selecione Ver especificação OpenAPI.

   O painel Ver especificação OpenAPI aparece mostrando a especificação OpenAPI da integração. Por padrão, a especificação OpenAPI gerada contém todos os gatilhos de API configurados na integração.

   • Para conferir a especificação OpenAPI de um gatilho de API específico, selecione o gatilho na lista suspensa APIs.
   • Para fazer o download da especificação OpenAPI como um arquivo YAML, clique em download .

Observação:só é possível visualizar e baixar a especificação OpenAPI, no formato YAML, para uma única integração por vez no editor de integração. Para conferir e baixar a especificação OpenAPI nos formatos YAML ou JSON, siga as instruções na seção API.

API

O método generateOpenApiSpec da API Application Integration permite visualizar a especificação OpenAPI da sua integração usando uma chamada de API.

Use o seguinte comando curl para conferir a especificação OpenAPI de uma ou mais integrações na mesma região:

Dica:o curl geralmente vem pré-instalado nos sistemas operacionais Linux e macOS. Caso não tenha curl, faça o download na página de versões e downloads do curl.

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:generateOpenApiSpec"
          

Substitua:

• TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: os nomes dos gatilhos de API na sua integração para os quais você quer ver a especificação OpenAPI.
• INTEGRATION_NAME: o nome da integração.
• DOC_TYPE: o tipo de documento a ser gerado. Os seguintes valores são aceitos: YAML ou JSON.
• PROJECT_ID: o ID do seu projeto Google Cloud .
• LOCATION: o local do projeto Google Cloud .
  Observação:só é possível ver a especificação OpenAPI para várias integrações na mesma região.

Entender a especificação OpenAPI

Application Integration gera a especificação OpenAPI para suas integrações publicadas de acordo com o padrão OpenAPI Specification 3.0. A tabela a seguir descreve os elementos da especificação OpenAPI gerados no Application Integration:

Elemento	Descrição
openapi	A versão da especificação OpenAPI usada.
info	Informações sobre a integração, como nome (título), descrição e versão publicada.
servers	Os URLs do servidor que hospedam a integração.
paths	Os caminhos são criados para cada gatilho de API selecionado na integração. O URL do servidor combinado com o caminho constitui o endpoint de API para fazer chamadas de API. Os campos Request e Response são preenchidos com base nas variáveis de entrada e saída configuradas para o gatilho de API correspondente. Observação:no momento, o Application Integration oferece suporte apenas a um conjunto limitado de palavras-chave do esquema JSON. Para informações sobre as palavras-chave aceitas, consulte Considerações.
components	O campo schemas contém o esquema JSON para as variáveis de entrada e saída do gatilho de API. O campo securitySchemes contém as informações de autenticação dos gatilhos de API.

Considerações

As seguintes considerações se aplicam ao visualizar a especificação OpenAPI da sua integração:

• A especificação OpenAPI é gerada apenas para integrações publicadas.
• A especificação OpenAPI é gerada apenas para integrações configuradas com um ou mais gatilhos de API.
• A especificação OpenAPI é gerada apenas para integrações na mesma região.
• A especificação OpenAPI é gerada no formato YAML por padrão. Para gerar e visualizar a especificação OpenAPI no formato JSON, defina o parâmetro fileFormat como JSON na chamada de API.
• No momento, Application Integration é compatível apenas com o seguinte conjunto limitado de palavras-chave do esquema JSON:
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• Ao validar a especificação OpenAPI usando o Swagger Editor, você pode encontrar erros semânticos relacionados aos caminhos da API, semelhantes à imagem a seguir:

  

  Esses erros podem ser ignorados com segurança. A especificação OpenAPI ainda é válida.

A seguir

• Crie agentes de conversação com a integração de aplicativos.
• Saiba mais sobre gatilhos de API.
• Saiba mais sobre Testar e publicar integrações.