Etapa REST

Envie uma solicitação de serviço da web REST de saída para um sistema externo.

Nota:

Etapa REST 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.

O serviço Web REST de saída é um recurso da plataforma que permite recuperar, criar, atualizar ou excluir dados em um servidor de serviços Web compatível com a arquitetura REST.

Funções e disponibilidade

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

Campos

Campo	Descrição
Conexão	Tipo de conexão a ser usado. Definir conexão em linha: Defina as informações de conexão na etapa de ação. Usar alias de conexão: Defina as informações de conexão usando a tabela de alias de conexão. 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 Introdução a credenciais, conexões e aliases.
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 a função de administrador ou flow_designer podem criar ou selecionar um registro 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. O valor da credencial é exibido como uma cápsula de dados de Senha (criptografada bidirecionalmente) no painel de dados. Nota: Este campo está disponível quando Usar Alias de Conexão é selecionado na lista Conexão.
Alias de credencial	Alias de credencial que o sistema usa para executar a etapa de ação. Usuários com a função de administrador ou flow_designer podem criar ou selecionar um registro de conexão associado. Usar um alias elimina a necessidade de configurar várias credenciais ao usar uma ação em vários ambientes. Da mesma forma, se as informações de credencial 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. O valor da credencial é exibido como uma cápsula de dados de Senha (criptografada bidirecionalmente) no painel de dados. Nota: Este campo está disponível quando Definir conexão em linha é selecionado na lista Conexão.
Usar MID	Opção para usar um ServiceNow® MID Server para executar o Etapa REST. Marque esta caixa de seleção para exibir os campos Aplicação MID e Recursos. Nota: O sistema não registra em log a solicitação REST, a resposta e os dados de tempo de execução do parâmetro enviados por meio de um MID Server da mesma forma que ocorre o registro em log de serviços Web de saída. Em vez disso, você pode exibir esses dados nos Detalhes de execução do fluxo.
URL Base	URL base da solicitação REST. Se Usar Alias de Conexão estiver selecionado, este campo exibirá o URL base associado ao alias. Você pode substituir o URL base clicando no ícone de cadeado (ícone de ) e inserindo o seu próprio. Se Definir conexão em linha estiver selecionado, insira um URL base para a conexão.
Testar etapa REST	Botão para testar a etapa REST. Para testar, selecione o botão Testar etapa REST. Insira os valores de entrada necessários e selecione o botão Executar teste. Após as execuções de teste, todas as saídas de etapa ou mensagens de erro são exibidas na seção Resultados de testes da janela de teste.
Tempo limite de conexão	Número de milissegundos que o sistema espera por uma conexão de host bem-sucedida. Se a etapa não estabelecer uma conexão bem-sucedida durante esse tempo, a solicitação de conexão expirará. Se Definir conexão em linha estiver selecionado, insira um valor de tempo limite para a conexão. Deixe este campo em branco para usar o valor de tempo limite de conexão padrão do sistema.
Seleção de MID	Opção para selecionar o MID Server ou Cluster do MID específico. Seleção automática do MID Server: seleciona o MID Server automaticamente. MID Server específico: usa o MID Server selecionado. Cluster do MID específico: usa o Cluster do MID selecionado. Este campo fica disponível quando Definir conexão em linha é selecionado na lista Conexão e Usar MID estiver marcado
Aplicação MID	Capacidades que o MID Server deve oferecer para estar qualificado para seleção. O sistema executa a etapa de ação de um MID Server que oferece suporte aos recursos selecionados. Este campo está disponível quando Definir conexão em linha é selecionado na lista Conexão, a caixa de seleção Usar MID está habilitada e Selecionar automaticamente o MID Server está selecionado na lista Seleção de MID.
Capacidades	Capacidades que o MID Server deve oferecer para estar qualificado para seleção. O sistema executa a etapa de ação de um MID Server que oferece suporte aos recursos selecionados. Este campo está disponível quando Definir conexão em linha é selecionado na lista Conexão, a caixa de seleção Usar MID está habilitada e Selecionar automaticamente o MID Server está selecionado na lista Seleção de MID.
MID Server	Cápsula de dados do MID Servernecessário. Este campo está disponível quando Definir conexão em linha é selecionado na lista Conexão, a caixa de seleção Usar MID está habilitada e MID Server específico é selecionado na lista Seleção de MID.
Cluster do MID	Cápsula de dados para o cluster MID que você deseja usar. Este campo fica disponível quando Definir conexão em linha é selecionado na lista Conexão, Usar MID estiver marcado e Cluster de MID específico estiver selecionado na lista Seleção de MID.
Criar solicitação	Opção para criar a solicitação manualmente, importar uma especificação OpenAPI ou importar uma mensagem REST. Manualmente: crie entradas de ação e preencha o formulário de etapa REST manualmente. Da especificação OpenAPI: importe uma especificação OpenAPI para gerar entradas de ação e preencha o formulário de etapa REST. Para obter mais informações, consulte Suporte OpenAPI na etapa REST. Da mensagem REST: importe uma mensagem REST da plataforma. Para obter mais informações, consulte Importar uma mensagem REST para uma etapa REST.
Origens de API	Opção para selecionar uma especificação OpenAPI 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 para o YAML ou JSON ou copiando e colando o conteúdo. Nota: Este campo está disponível quando você seleciona Da especificação OpenAPI na lista Solicitação de compilação.
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. Nota: Este campo está disponível quando você seleciona Da especificação OpenAPI na lista Solicitação de compilação.
Mensagem REST	Nome da mensagem REST a ser importada. Selecione uma mensagem REST na lista. Nota: Este campo está disponível quando você seleciona De mensagem REST na lista Solicitação de compilação.
Função da Mensagem REST	Nome da função a ser importada da mensagem REST. As opções disponíveis são determinadas pelos métodos HTTP associados à mensagem REST selecionada. Nota: Este campo está disponível quando você seleciona De mensagem REST na lista Solicitação de compilação.
Importar mensagem REST	Botão para importar a mensagem REST. Nota: Este campo está disponível quando você seleciona uma mensagem REST no campo Mensagem REST.
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.
Tipo de solicitação	Formato da solicitação. As opções incluem. Texto: uma solicitação em JSON, XML ou outro formato de texto. Binário: uma solicitação em formato de arquivo binário. Várias partes: uma solicitação que consiste em vários tipos de conteúdo. Formulário codificado por URL: uma solicitação em uma consulta codificada por URL. Nota: Este campo é editável quando o Método HTTP é POST, PUT, PATCHou DELETE.
Corpo da solicitação [Texto]	Corpo da solicitação no formato JSON ou XML. Os detalhes de execução do fluxo exibem o corpo da resposta como um link para o visualizador de texto incorporado ou o sys_id do registro de anexo que contém a resposta. Nota: Este campo será editável se você selecionar Texto na lista Tipo de solicitação.
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.
Nome, Tipo de Peça, Valor	Conteúdo de uma solicitação de várias partes. Para cada peça, especifique seu nome, tipo de peça e valor usando os campos individualmente ou usando um script em linha para todas as peças. Você pode especificar os valores de várias partes clicando no ícone de alternância de script ( ícone de ) e editando o script. Para obter mais informações sobre scripts em linha, consulte Scripts em linha. Nome: o nome da peça. Pode ser qualquer cadeia de caracteres válida. Tipo de peça: o tipo da peça. Selecione Texto ou Arquivo. Texto: o texto da peça. Depois que o texto for selecionado, você poderá especificar o tipo de conteúdo. Arquivo: o arquivo da peça. Quando Arquivo é selecionado, o Valor deve ser o sys_id do registro de anexo que contém o conteúdo. Você pode pesquisar este registro em uma etapa anterior ou defini-lo como um valor de entrada. Depois que o arquivo for selecionado, você poderá especificar o nome do arquivo e o tipo de conteúdo. Em Definir nome do arquivo, selecione Do anexo para usar o nome de arquivo do registro anexado ou selecione Da entrada Nome do arquivo para inserir o seu próprio nome. Em Definir tipo de conteúdo, selecione Do anexo para usar o tipo de conteúdo do registro anexado ou selecione Da entrada Tipo de conteúdo para inserir o seu próprio. Valor: o conteúdo da peça. Para texto, o valor é o conteúdo do texto. Para um arquivo, o valor é o sys_id do registro de anexo que contém o conteúdo. Nota: Esses campos estão disponíveis ao selecionar Multipart na lista Tipo de solicitação.
Nome, valor	Conteúdo de uma solicitação codificada por URL de formulário. Especifique cada parte da solicitação codificada por URL com um par nome-valor usando os campos individualmente ou usando um script em linha para todas as partes. Você pode especificar o script em linha dos valores codificados por URL do formulário clicando no ícone de alternância de script (ícone de ) e editando o script. Para obter mais informações sobre scripts em linha, consulte Scripts em linha. Nota: Este campo está disponível quando você seleciona Formulário codificado por URL 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.
Salvar como anexo	Opção para especificar se a resposta deve ser salva como um registro na tabela Anexo [sys_attachment].
Nome do Arquivo Anexado	Nome do anexo criado pela resposta REST. Por exemplo, rest-response.txt. Nota: Este campo está disponível quando Salvar como anexo é selecionado.
Registro de arquivo de anexo	Registro de destino ao qual o anexo está associado. O registro de destino deve ser uma cápsula de dados do tipo Registro. Por exemplo, um registro de incidente específico. Você pode pesquisar este registro em uma etapa anterior ou defini-lo como uma variável de entrada. Os detalhes da execução do fluxo exibem o sys_id do registro associado. Nota: Este campo está disponível quando Salvar como anexo é selecionado.

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 Avaliação de erro de ação.

Limites de tamanho de resposta REST

Por padrão, o sistema limita o tamanho das respostas REST que não são salvas como anexos a 5 MB. As respostas REST diretas que excedem esse limite geram um erro. Para oferecer suporte a tamanhos de resposta maiores, salve a resposta como um anexo ou aumente o limite de tamanho da resposta com a propriedade do sistema glide.pf.rest.response_payload_max_size. Esta propriedade do sistema oferece suporte a um valor máximo de 1024, o que limita a resposta REST a 10 MB.

Analisando uma resposta REST

As chamadas de REST API retornam dados no corpo da resposta. Os dados do corpo da resposta geralmente são estruturados no formato JSON ou XML. Você pode usar um Etapa de script para analisar os dados estruturados em variáveis para usar em outro lugar na ação ou em um fluxo. Há também um para analisar um corpo de resposta que está em um formato XML.

A estratégia geral para obter dados extraídos da resposta é fazer o seguinte.

1. Revise o corpo da resposta para selecionar os dados a serem retornados.
2. Crie variáveis de entrada e saída na etapa de Script.
   • Crie uma variável de entrada para passar no corpo da resposta da etapa REST.
   • Crie variáveis de saída para retornar dados da resposta.
3. Crie um script para analisar e mapear dados.
   • Use o método JSON.parse() em uma etapa de script para analisar um corpo de resposta JSON.
   • Mapeie os dados analisados para as variáveis de saída.
4. Crie saídas de ação para as variáveis de saída para disponibilizar os dados para um fluxo.

Para obter um exemplo detalhado, consulte a seção Analisando uma resposta REST no treinamento do desenvolvedor REST no IntegrationHub.