Etapa OpenAPI

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 5 min. de leitura

    • Importe a especificação OpenAPI de um serviço Web REST de saída de terceiros e crie uma integração para o serviço Web. Os detalhes da solicitação para a operação de REST API subjacente são derivados da especificação OpenAPI.

    Para o corpo da resposta de saída JSON, o sistema cria uma saída de objeto de dados complexo a partir da especificação OpenAPI.

    Nota:
    Etapa OpenAPI não está disponível no sistema básico e requer a assinatura de ServiceNow® IntegrationHub. Depois que o plug-in necessário for ativado, a etapa ficará visível em Integrações.

    Funções e disponibilidade

    Disponível como uma etapa de ação do Designer de ações. Usuários com as funções action_designer e open_api_admin ou admin podem criar uma ação personalizada com uma ou mais etapas de ação.

    Campos

    Campo Descrição
    Alias de Conexão Registro de alias de conexão e credencial que o sistema usa para executar a etapa de ação. Usuários com as funções action_designer e connection_admin ou admin podem selecionar um registro de alias de conexão associado. Usar um alias elimina a necessidade de configurar várias credenciais e perfis de informações de conexão ao usar uma ação em vários ambientes. Da mesma forma, se as informações de conexão forem alteradas, você não precisará atualizar sua ação personalizada. Para saber mais sobre conexões e credenciais, consulte credenciais, conexões e aliases.
    URL Base URL base do alias de conexão da solicitação REST.
    Origens de API

    Opção para selecionar uma Especificação OpenAPI v2.0 e v3.0 usada para construir a solicitação ou selecionar Importar OpenAPI para importar uma nova Especificação OpenAPI. Você pode importar especificações fornecendo um URL e credenciais para o YAML ou JSON, ou copiando e colando o conteúdo.
    Operações de API

    Opção para selecionar uma operação na lista. As operações disponíveis são fornecidas pela Especificação OpenAPI no campo Origem da API.
    Caminho do Recurso Caminho para o recurso.
    Método HTTP Método HTTP usado para processar a solicitação.
    • OBTER
    • POST
    • PUT
    • PATCH
    • DELETE
    Parâmetros de Consulta

    Pares de nome-valor a serem passados para o endpoint REST. Você pode criar esses parâmetros manualmente ou arrastar variáveis de entrada para os campos de parâmetro e então atribuir um valor.

    Ofereça suporte a solicitações de etapa REST que contêm nomes de parâmetro de consulta duplicados. Se você criar uma solicitação REST que contenha nomes de parâmetro de consulta duplicados, Flow Designer adicionará os parâmetros de consulta à solicitação na mesma ordem em que você os definiu.

    Nota:
    Ao importar uma especificação de OpenAPI, o sistema adiciona todos os parâmetros e cabeçalhos presentes na especificação à etapa REST. Revise os valores da etapa REST final e remova os parâmetros que você não deseja enviar na solicitação. Por exemplo, se a API aceitar cabeçalhos de tipo de conteúdo para JSON e XML, o sistema adicionará ambos os cabeçalhos à etapa REST. Remova um dos cabeçalhos, dependendo do tipo de conteúdo que você deseja receber na resposta.
    Cabeçalhos

    Cabeçalhos a serem enviados com a solicitação. Você pode criar cabeçalhos manualmente ou arrastar variáveis de entrada para os campos de parâmetro e, em seguida, atribuir um valor.

    Ofereça suporte a solicitações de etapa REST que contêm cabeçalhos de solicitação duplicados. Se você criar uma solicitação REST que contenha cabeçalhos de solicitação duplicados, cabeçalhos serão enviados na mesma ordem em que você os definiu.

    Nota:
    Ao importar uma especificação de OpenAPI, o sistema adiciona todos os parâmetros e cabeçalhos presentes na especificação à etapa REST. Revise os valores da etapa REST final e remova os parâmetros que você não deseja enviar na solicitação. Por exemplo, se a API aceitar cabeçalhos de tipo de conteúdo para JSON e XML, o sistema adicionará ambos os cabeçalhos à etapa REST. Remova um dos cabeçalhos, dependendo do tipo de conteúdo que você deseja receber na resposta.
    Anexo Registro de anexo que contém a solicitação. Você pode pesquisar ou criar este registro em uma etapa anterior e defini-lo como uma variável de entrada. Crie-o usando as APIs JSONStreamingBuilder e XMLStreamingBuilder na etapa de Script.
    Nota:
    Este campo está disponível quando você seleciona Binário na lista Tipo de solicitação.
    Habilitar políticas de novas tentativas para habilitar a política de nova tentativa. Para obter mais informações, consulte Política de nova tentativa.
    Substituir política padrão para alias Opção para substituir a política de nova tentativa padrão. Esta caixa de seleção não é aplicável quando Definir conexão em linha é selecionado na lista de conexão.
    Política de nova tentativa Política de repetição padrão associada ao Alias de conexão. Se a opção Substituir política padrão para alias estiver selecionada, será possível substituir a política de nova tentativa padrão e selecionar outra política de nova tentativa existente com base em seus requisitos.

    Campos de avaliação de erro de ação

    Campo Descrição
    Se esta etapa falhar Opção para continuar executando a próxima etapa ou ir para a avaliação de erro. Para usar o código de status da etapa ou a mensagem para uma condição de erro de ação personalizada, consulte Action error evaluation.
    Campos na etapa Abrir API

    Campos de avaliação de erro de ação

    Campo Descrição
    Se esta etapa falhar Opção para continuar executando a próxima etapa ou ir para a avaliação de erro. Para usar o código de status da etapa ou a mensagem para uma condição de erro de ação personalizada, consulte Action error evaluation.

    Limitações conhecidas

    Crie uma etapa de OpenAPI a partir de uma especificação de OpenAPI com essas limitações.

    Tipos de mídia do corpo da solicitação
    O corpo da solicitação é compatível somente com tipos de mídia JSON.
    Nota:
    Um objeto de saída do tipo cadeia de caracteres é criado quando o esquema OpenAPI tem additionalProperties ou nenhuma propriedade.
    Componentes do OpenAPI 3.0

    O OpenAPI 3.0 adiciona novos componentes ao Swagger 2.0 para descrever uma API com mais detalhes. O suporte a OpenAPI na etapa OpenAPI oferece suporte a alguns, mas não a todos esses componentes. A etapa OpenAPI não é compatível com esses componentes.

    • Objeto de esquema: propriedades additionalProperties
    • Objeto discriminador
    • Objeto de informação: campos de termos de serviço, contato e licença
    • Objeto de exemplo
    • Objeto de link
    • Objeto de retorno de chamada
    • Objeto do Esquema de Segurança
    • Objeto de requisitos de segurança
    • Objeto de marcador
    • Objeto de documentação externa
    • Objeto do servidor
    • Extensões de especificação
    • Referências recursivas

    Mais informações sobre esses componentes estão disponíveis na documentação do OpenAPI. Consulte Especificação OpenAPI.

    Número máximo de operações compatíveis
    O número de operações de API é limitado a 500 por padrão. No entanto, usando a propriedade do sistema glide.rest.openapi.max_operation_limit, você pode configurar o número de operações de 1 a 1000.