Etapa REST
Envie uma solicitação de serviço da web REST de saída para um sistema externo.
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 da Web que oferece suporte à arquitetura REST.
Funções e disponibilidade
Disponível como uma etapa de ação de Workflow Studio. 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 usada.
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 flow_designer ou administrador 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 mudarem, 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 em 2 vias) 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 flow_designer ou administrador 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 mudarem, 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 em 2 vias) no painel de dados. Nota: Este campo está disponível quando Defina a 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 Aplicação MID e. . campos. Nota: O sistema não registra os dados de tempo de execução de parâmetros, resposta e solicitação REST enviados por meio de um MID Server da mesma forma que isso Registro em log de serviços web de saída ocorre. Em vez disso, você pode exibir esses dados no Detalhes da execução do fluxo . |
| URL base | URL base da solicitação REST.
|
| Testar etapa REST | Botão para testar a etapa REST. Para testar, selecione Etapa REST de teste botão. Insira os valores de entrada necessários e selecione Executar teste botão. Após a execução do teste, todas as saídas de etapa ou mensagens de erro são exibidas na seção Resultados de teste 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 fizer uma conexão bem-sucedida durante esse tempo, a solicitação de conexão atingirá o tempo limite. Se Defina a conexão em linha 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.
Nota: Evite definir Tempo limite de conexão valor zero, pois isso pode causar uma conexão obsoleta. |
| Seleção de MID |
Opção para selecionar um MID Server ou cluster DO MID específico. Escolha qualquer uma das opções a seguir.
|
| Aplicação de MID | . MID Server suporte necessário para ser 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 Defina a conexão em linha Selecionado na lista Conexão, Usar MID a caixa de seleção está habilitada, e. Seleção automática DO MID Server Selecionado na lista Seleção de MID. |
| Capacidades | . MID Server suporte necessário para ser 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 Defina a conexão em linha Selecionado na lista Conexão, Usar MID a caixa de seleção está habilitada, e. Seleção automática DO MID Server Selecionado na lista Seleção de MID. |
| MID Server | Cápsula de dados do necessário MID Server. Este campo está disponível quando Defina a conexão em linha Selecionado na lista Conexão, Usar MID a caixa de seleção 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.
|
| Origens de API | Opção para selecionar uma Especificação OpenAPI usada para construir a solicitação ou selecione OpenAPI de importação 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 de solicitações 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 Origem da API campo. Nota: Este campo está disponível quando você seleciona Da especificação OpenAPI Na lista de solicitações 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 Da mensagem REST Na lista de solicitações 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 Da mensagem REST Na lista de solicitações 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 Mensagem REST campo. |
| Caminho do recurso | Caminho do recurso. |
| Método HTTP | Método HTTP usado para processar a solicitação.
|
| 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, Workflow Studio 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 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.
Nota: Este campo é editável quando Método HTTP . PUBLICAR , COLOCAR , PATCH ou EXCLUIR . |
| Corpo da solicitação [Texto] | Corpo da solicitação no formato JSON ou XML. Os detalhes da execução do fluxo exibem o corpo da resposta como um link para o visualizador de texto incorporado ou o sys_id do registro do 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 parte, especifique seu nome, tipo de peça e valor usando os campos individualmente ou usando um script em linha para todas as partes. Você pode especificar os valores de várias partes clicando no ícone Alternar script (
Nota: Esses campos ficam disponíveis quando você seleciona Várias partes Na lista Tipo de solicitação. |
| 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 de valores codificados por URL do formulário clicando no ícone Alternar script (  e editando o script. Para obter mais informações sobre script 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. |
| Tentar Política Novamente | 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. |
) e inserindo o seu próprio.Avaliação de erro de ação
- Se esta etapa falhar
- Tipo de dados: Choice
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 da resposta REST
Por padrão, o sistema limita o tamanho das respostas REST que não são salvas como anexos a 5 MB. 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 glide.pf.rest.response_payload_max_sizepropriedade do sistema. Esta propriedade do sistema oferece suporte a um valor máximo de 10240 KB, o que limita a resposta REST a 10 MB de tamanho.
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 a serem usadas em outro lugar na ação ou em um fluxo. Há também um XML parser step Para analisar um corpo de resposta que está em um formato XML.
- Revise o corpo da resposta para selecionar os dados a serem retornados.
- Crie variáveis de entrada e saída na etapa 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.
- Crie um script para analisar e mapear dados.
- Use
JSON.parse()Método em uma etapa de script para analisar um corpo de resposta JSON. - Mapeie os dados analisados para as variáveis de saída.
- Use
- Crie saídas de ação para as variáveis de saída para disponibilizar os dados para um fluxo.