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 compatível com a 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. Os usuários com a função flow_designer ou admin 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 (criptografia de 2 vias) no painel de dados. Nota: Este campo estará disponível quando Usar alias de conexão Está selecionado na lista de Conexões. |
| Alias de credencial | Alias de credencial que o sistema usa para executar a etapa de ação. Os usuários com a função flow_designer ou admin podem criar ou selecionar um registro de conexão associado. O uso de 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 (criptografia de 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 o. MID e. . campos. Nota: O sistema não registra 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 de 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 estabelecer 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 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.
Nota: Evite definir o valor de Tempo limite de conexão como 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 deve ser compatível para ser elegível para a seleção. O sistema executa a etapa de ação de um MID Server que oferece suporte às capacidades selecionadas. Este campo estará disponível quando Defina a conexão em linha É selecionado na lista de Conexões, Use MID a caixa de seleção está habilitada, e. MID Server de seleção automática Está selecionado na lista Seleção DO MID. |
| Capacidades | . MID Server deve ser compatível para ser elegível para a seleção. O sistema executa a etapa de ação de um MID Server que oferece suporte às capacidades selecionadas. Este campo estará disponível quando Defina a conexão em linha É selecionado na lista de Conexões, Use MID a caixa de seleção está habilitada, e. MID Server de seleção automática Está selecionado na lista Seleção DO MID. |
| MID Server | Cápsula de dados do necessário MID Server. Este campo estará disponível quando Defina a conexão em linha É selecionado na lista de Conexões, Use MID a caixa de seleção está habilitada, e. MID Server específico Está selecionado na lista Seleção DO 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.
|
| Origem da 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 fica disponível quando você seleciona Da especificação OpenAPI Da lista de solicitações de compilação. |
| Operação 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 fica disponível quando você seleciona Da especificação OpenAPI Da 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 fica disponível quando você seleciona Da mensagem REST Da 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 fica disponível quando você seleciona Da mensagem REST Da 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 na 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 OpenAPI, o sistema adiciona todos os parâmetros e cabeçalhos presentes na especificação à etapa REST. Revise os valores finais da etapa REST 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 OpenAPI, o sistema adiciona todos os parâmetros e cabeçalhos presentes na especificação à etapa REST. Revise os valores finais da etapa REST 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 é PUBLICAÇÃO , 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 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 fica 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 com 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 de alternância de script (
Nota: Estes campos estão disponíveis quando você seleciona Várias partes 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 de valores codificados por URL do formulário clicando no ícone de alternância de script (  ) e editando o script. Para obter mais informações sobre script em linha, consulte Scripts em linha.Nota: Este campo fica disponível quando você seleciona URL do formulário codificado Na lista Tipo de solicitação. |
| Habilitar políticas de novas tentativas | Opção para habilitar a política de novas tentativas. Para obter mais informações, consulte Política de novas tentativas . |
| Substituir política padrão para alias | Opção para substituir a política de novas tentativas padrão. Esta caixa de seleção não é aplicável quando Defina a conexão em linha Está selecionado na lista de Conexões. |
| Tentar Política Novamente | Política de novas tentativas padrão associada a. Alias de conexão . Se Substituir política padrão para alias estiver selecionado, você pode substituir a política de novas tentativas padrão e selecionar outra política de novas tentativas existente com base em seu requisito. |
| 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 estará disponível quando Salvar como anexo está 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 estará disponível quando Salvar como anexo está 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 este 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 da 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 o.
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 o.
- Crie saídas de ação para as variáveis de saída para disponibilizar os dados para um fluxo.