Integração da especificação OpenAPI - Amazon Quick
O que é possível fazerAntes de começarPrepare a especificação e a autenticação da OpenAPIConfigurar a integração da especificação OpenAPIRequisitos de formato e padrãoAtributos não compatíveisPráticas recomendadas de esquemaExtensões compatíveisValidação do esquema e tratamento de errosGerenciar a integração da especificação OpenAPISolucionar problemas de integração com a especificação OpenAPI

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Integração da especificação OpenAPI

Com a integração da Especificação OpenAPI, você pode criar integrações personalizadas com base nos esquemas da OpenAPI. Isso permite que você se conecte a qualquer API que forneça uma especificação OpenAPI. Essa integração suporta somente a execução de ações e requer o nível Amazon Quick Pro ou superior.

O que é possível fazer

A integração da Especificação OpenAPI fornece conectividade baseada em esquema para ajudá-lo a trabalhar com personalização. APIs

Conector de ação

Execute ações com base nas especificações da OpenAPI. Execute chamadas de API, gerencie recursos e interaja com serviços personalizados por meio de ações geradas dinamicamente com base no esquema fornecido.

Configuração baseada em esquema

Importe as especificações da OpenAPI para gerar automaticamente ações e ações disponíveis. Support para validação de esquema JSON e mapeamento de parâmetros.

Antes de começar

Antes de configurar a integração da Especificação OpenAPI, verifique se você tem o seguinte:

  • Especificação OpenAPI (versão 3.0.0 ou superior) para sua API de destino.

  • Credenciais de autenticação de API (chave de OAuth API ou outras).

  • Amazon Quick Author ou superior.

  • Documentação da API e acesso ao endpoint.

Prepare a especificação e a autenticação da OpenAPI

Antes de configurar a integração no Amazon Quick, prepare suas credenciais de autenticação e especificação da OpenAPI. Sua especificação da OpenAPI deve atender aos requisitos específicos para uma integração bem-sucedida.

Requisitos básicos

Sua especificação da OpenAPI deve atender a esses requisitos básicos.

  • Versão OpenAPI - É necessária a versão 3.0.0 ou superior.

  • Formato do arquivo - somente no formato JSON (aplicativo/json).

  • Limite de tamanho de arquivo - Máximo de 1 MB para toda a especificação da OpenAPI.

  • Limite de operação - Mínimo de 1 e máximo de 100 operações de API por conector.

Campos de esquema obrigatórios

Sua especificação da OpenAPI deve incluir essas seções obrigatórias.

abrir API

A versão da OpenAPI que está sendo usada (deve ser “3.0.0" ou superior).

info

Informações do serviço, incluindo título, descrição e versão.

servidores

URL base e informações do servidor para conectividade com a API.

caminhos

Definições de endpoint de API com métodos e operações HTTP.

Esquemas de autenticação compatíveis

Prepare as credenciais de autenticação com base nos métodos de autenticação suportados nas especificações da OpenAPI.

OAuth 2.0

Suporta os fluxos de Concessão de Código de Autorização e Concessão de Credenciais de Cliente. Requer definições de AuthorizationURL, TokenURL e escopos no esquema de segurança.

Chave de API

Autenticação de chave de API transmitida em parâmetros de consulta ou cabeçalhos.

Sem autenticação

Opção padrão quando nenhum esquema de segurança é definido na especificação.

nota

Esquemas de autenticação não suportados na especificação OpenAPI serão ignorados e o conector usará como padrão nenhuma autenticação.

Configurar a integração da especificação OpenAPI

Depois de preparar sua especificação e credenciais de autenticação da OpenAPI, siga estas etapas para criar sua integração com a Especificação da OpenAPI.

  1. No console do Amazon Quick, escolha Integrações.

  2. Clique em Adicionar (mais o botão “+”).

  3. Na página Adicionar esquema, selecione Importar esquema e escolha um esquema para importar.

  4. Escolha Próximo.

  5. Preencha os detalhes da integração, incluindo nome e descrição.

  6. Analise as ações disponíveis geradas a partir da sua especificação da OpenAPI.

  7. Selecione Criar e continuar.

  8. Escolha usuários com os quais compartilhar a integração.

  9. Clique em Next.

Resultados esperados

Após a configuração bem-sucedida, sua integração com a Especificação OpenAPI aparece na lista de integrações com ações geradas dinamicamente com base em seu esquema. A integração está disponível para uso em fluxos de trabalho, automações e agentes de IA do Amazon Quick, com tarefas correspondentes aos endpoints definidos na sua especificação da OpenAPI.

Requisitos de formato e padrão

Sua especificação da OpenAPI deve seguir esses requisitos de formato.

  • Padrões de caminho - devem seguir o padrão: ^/[^/]*(/[^/]*)*$ e começar com uma barra (/).

  • Operação IDs - Deve seguir o padrão:^[a-zA-Z0-9_ ]{1,256}$.

  • Descrições - Obrigatórias para todas as operações e parâmetros, máximo de 5000 caracteres.

  • Tipo de conteúdo - Só application/json é compatível com corpos de solicitação e resposta.

Atributos não compatíveis

Os seguintes recursos da OpenAPI não são suportados e causarão erros de validação.

  • Tipos de matriz - Esquemas com tipos de matriz (por exemplo,{"type": "array", "items": {"string"}}) não são suportados.

  • Palavras-chave de composição - as palavras-chave allOf, oneOf, anyOf e not não são suportadas.

  • Referências circulares - Referências circulares ou cíclicas ($ref dentro de $ref) não são suportadas.

  • Estruturas aninhadas complexas - Evite estruturas de objetos profundamente aninhadas sempre que possível.

Práticas recomendadas de esquema

Siga essas melhores práticas ao criar sua especificação OpenAPI.

Escreva descrições eficazes

Use essas diretrizes para escrever descrições claras e úteis.

  • Descrições da operação - Descreva o que a operação faz, quando usá-la e como ela se comporta.

  • Descrições dos parâmetros - Explique de forma concisa a finalidade e o impacto do parâmetro no comportamento da operação.

  • Conteúdo independente — garanta que as descrições forneçam orientação suficiente sem referências externas.

  • Clareza da dependência - torne as dependências entre as operações explícitas nas descrições.

  • Referências de operação - Use operationId ao se referir a outras operações, não a caminhos de API.

Recomendações de estrutura de parâmetros

Estruture seus parâmetros para uma usabilidade ideal.

  • Nivele objetos complexos - Em vez de objetos aninhados, use parâmetros separados (por exemplo, data_inicial, hora_inicial, data_final, hora_final).

  • Use formatos padrão - Use valores de formato padrão como “data e hora” ou “data” para datas e horas ISO-8601.

  • Nomes de parâmetros claros - Use nomes de parâmetros descritivos que indiquem claramente sua finalidade.

  • Marcação de campo obrigatória - marque corretamente os parâmetros como obrigatórios ou opcionais com base no comportamento da API.

Extensões compatíveis

Oferecemos suporte a extensões OpenAPI personalizadas para aprimorar a experiência do usuário.

x-amzn-form-display-nome

Use no nível do parâmetro para substituir o nome do campo padrão exibido nos formulários de confirmação. Atualmente suportado somente para parâmetros do corpo da solicitação.

"x-amzn-form-display-name": "User Name"
x-amzn-operation-type

Defina se uma operação deve ser tratada como “leitura” ou “gravação”. Por padrão, os métodos GET são operações de “leitura” e todos os outros métodos HTTP são operações de “gravação”.

"x-amzn-operation-type": "read"

Validação do esquema e tratamento de erros

Quando você carrega uma especificação da OpenAPI, realizamos uma validação abrangente.

  • Validação do tamanho do arquivo - Garante que a especificação não exceda 1 MB.

  • Validação da contagem de operações - Verifica se de 1 a 100 operações estão definidas.

  • Validação da estrutura do esquema - Verifica os campos obrigatórios e a formatação adequada.

  • Validação do esquema de segurança - Valida os métodos de autenticação compatíveis.

  • Validação do tipo de conteúdo - Garante que somente application/json seja usado.

Os erros de validação aparecem abaixo do editor de esquemas e devem ser resolvidos antes que a integração possa ser criada. Os problemas comuns de validação incluem:

  • Campos obrigatórios ausentes (openapi, informações, servidores, caminhos).

  • Padrões de caminho ou operação IDs inválidos.

  • Recursos de esquema não suportados (matrizes, palavras-chave de composição).

  • Descrições ausentes ou excessivamente longas.

  • Referências circulares nas definições do esquema.

Gerenciar a integração da especificação OpenAPI

Depois de criar sua integração com a Especificação OpenAPI, você pode gerenciá-la por meio de várias opções.

Compartilhe a integração

Você pode compartilhar conectores de ação da Especificação OpenAPI com outros usuários em sua organização.

  1. Na página de detalhes da integração com a OpenAPI, escolha Compartilhar.

  2. Configure as opções de compartilhamento:

    • Compartilhe com usuários específicos: insira nomes de usuário ou endereços de e-mail.

    • Compartilhe com a organização - Disponibilize para todos os usuários da sua organização.

  3. Defina níveis de permissão para acesso compartilhado.

  4. Escolha Compartilhar integração para aplicar as configurações de compartilhamento.

Excluir integração

Siga estas etapas para remover permanentemente sua integração com a OpenAPI.

  1. Na página de detalhes da integração com a OpenAPI, escolha Excluir.

  2. Analise o impacto da exclusão, incluindo quaisquer fluxos de trabalho ou automações usando essa integração.

  3. Digite o nome da integração para confirmar a exclusão.

  4. Escolha Excluir integração para removê-la permanentemente.

Solucionar problemas de integração com a especificação OpenAPI

Use essas dicas de solução de problemas para resolver problemas comuns de integração da Especificação OpenAPI.

Erros de validação de esquema

Certifique-se de que sua especificação da OpenAPI siga o formato correto e inclua todos os campos obrigatórios. Use um validador OpenAPI para verificar seu esquema antes de importar.

Nenhuma tarefa gerada

Verifique se sua especificação da OpenAPI inclui definições de caminho com métodos e operações HTTP. IDs As ações são geradas com base nas operações definidas em seu esquema.

Falhas de autenticação

Verifique se o esquema de autenticação definido na sua especificação da OpenAPI corresponde aos requisitos reais da API e se as credenciais estão configuradas corretamente.

Falhas na execução da ação

Revise os parâmetros de ação e garanta que eles correspondam às definições de parâmetros em sua especificação da OpenAPI, incluindo campos e tipos de dados obrigatórios.