Criação de uma atividade de serviço web REST

Use este procedimento para criar uma atividade de serviço web REST personalizada Orquestração .

Antes de Iniciar

Funções necessárias: web_service_admin, activity_admin, activity_creator

Por Que e Quando Desempenhar Esta Tarefa

Para criar e usar uma atividade de fluxo de trabalho de serviço web REST:

• Crie uma Criar uma mensagem REST se uma apropriada ainda não estiver configurada.
• Atribua a função web_service_admin a qualquer usuário que precise criar ou editar uma atividade REST personalizada.
• Determine uma aplicação, ou Escopo da aplicação, para esta atividade.
• Determine o Criar uma mensagem REST a ser usada para a atividade. Use este valor para substituir o endpoint configurado na mensagem REST.
• Opcionalmente, crie credenciais de autenticação básica. Use este valor para substituir as credenciais configuradas na mensagem SOAP.

Procedimento

1. Crie uma atividade personalizada.
   Esta ação cria uma atividade personalizada usando um modelo.
2. Depois de configurar as propriedades gerais e criar variáveis de entrada, configure o Comando de Execução do serviço web REST.

   Opção	Descrição
   Mapear as variáveis de entrada	Use as variáveis que você criou para configurar o comando que a Orquestração vai executar.
   Mensagem REST	Nome de uma mensagem REST existente a ser usada nesta atividade.
   Função da mensagem REST	Função da mensagem REST a ser usada para esta atividade.
   Endpoint	URL do endpoint para o serviço web REST que esta atividade usará. Insira um endpoint neste campo para substituir o endpoint configurado na mensagem REST. Clique no cadeado para abrir o campo de entrada.
   Substituições de variáveis	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. Parâmetros definidos na mensagem REST que usam $ {} podem ser dados atribuídos a partir deste modelo de atividade. Use a coluna Atributo adicional para configurar o sistema para não escapar o texto. Por padrão, o texto enviado para a mensagem REST tem escape. Se os usuários tiverem fornecido variáveis usando a Substituição de variável em mensagens REST de saída na mensagem REST, a coluna Nome será preenchida automaticamente.
   Cabeçalhos adicionais	Parâmetros de cabeçalho HTTP adicionais para a mensagem REST selecionada. Você também pode usar esses valores para substituir parâmetros herdados da mensagem REST.
   Parâmetros de consulta adicionais	Parâmetros de consulta adicionais para a mensagem REST selecionada. Você também pode usar esses valores para substituir parâmetros herdados da mensagem REST.
   Usar MID Server	Marque a caixa que determina se um MID Server deve ser usado para invocar o serviço web REST. Nota: Se a função de mensagem do serviço web REST definir um MID Server, esse MID Server será usado em vez do selecionado aqui.
   Requer recursos do MID Server	MID Server com os recursos do MID Server apropriados para conexão com o endpoint REST. Por padrão, o sistema seleciona um MID Server que tenha o recurso REST. Este campo está disponível quando a caixa de seleção Usar MID Server está marcada.
   Tempo limite	Duração permitida da solicitação de serviço web REST em segundos antes do tempo limite. O padrão é 10.
   Autenticação	Determina que tipo de autenticação é necessária para o endpoint. As opções são: Usar credenciais existentes na mensagem REST: usa definições de credencial da definição de mensagem REST. Substituir por credenciais de autenticação básica: usa credenciais Habilitar autenticação básica para SOAP de saída para substituir as credenciais na definição de mensagem REST. As credenciais de autenticação básica devem ser provisionadas antes de ficarem disponíveis para seleção. Substituir por credenciais de autenticação de certificado: usa um certificado, como uma chave privada, para substituir as credenciais na definição de mensagem REST. Substituir por credenciais de autenticação básica e de certificado: usa tanto a autenticação básica e a por certificado para substituir as credenciais na definição de mensagem REST. Substituir por credenciais de autenticação OAuth: usa credenciais OAuth 2.0 para substituir as credenciais na definição de mensagem REST. A mensagem REST selecionada para esta atividade deve ter seu Tutorial OAuth 2.0 – criar uma mensagem REST definido como OAuth 2.0 e os perfis OAuth e escopos configurados corretamente.
   Credenciais	Requer credenciais de autenticação básicas de endpoint REST. Este campo está disponível quando Substituir por credenciais de autenticação básica é selecionado no campo Autenticação. Somente as credenciais de autenticação básica aparecem na lista de seleção, que inclui credenciais armazenadas na instância e IDs de credencial de um sistema de armazenamento externo. Se você estiver usando credenciais armazenadas em um cofre CyberArk, poderá substituir o cofre padrão definido no arquivo de configuração do MID Server. Consulte Configuração do MID Server para CyberArk para obter detalhes. Adicione o nome de um cofre diferente como um prefixo ao ID de credencial, separado por dois pontos. Por exemplo, newsafe:orch-test-f5.
   Perfil de Protocolo	Autenticação baseada em certificados a ser usada. Este campo está disponível quando as seleções em Autenticação são Substituir por credenciais de autenticação de certificado ou Substituir por credenciais de autenticação básica e de certificado.
   Perfil OAuth	Perfil do provedor OAuth para esta mensagem REST. Consulte Especificação de um perfil OAuth para obter mais informações.

   Nota:

   Você pode mapear valores de parâmetro em uma carga de teste para variáveis na guia Saídas automaticamente. Consulte variáveis de saída do mapeamento automático.

O que Fazer Depois

Conclua a criação de sua atividade de serviço web REST criando variáveis de saída, criando uma regra de análise ou Condições. Consulte o tópico criar atividades personalizadas para conhecer as opções de modelo.

Mapeamento automático de variáveis de saída de atividade REST

Com o ServiceNow designer de atividades você pode mapear valores de parâmetro em uma carga de teste REST para variáveis na fase Saída automaticamente.

Antes de Iniciar

Funções necessárias: web_service_admin, activity_admin, activity_creator

Por Que e Quando Desempenhar Esta Tarefa

Nota:

Você pode testar variáveis de entrada de cada fase do designer de atividades se tiver fornecido informações suficientes para a Orquestração contatar o endpoint e retornar dados. Normalmente, a fase de Comando de Execução é o ponto em que suas entradas estão prontas para teste.

Procedimento

1. No designer de atividades, prossiga para a fase de Comando de Execução.
2. Defina um MID Server apropriado, se solicitado.
   O teste falhará se o MID Server não puder ser encontrado ou se ele não puder se conectar ao destino.
3. Clique em Testar atividade para testar os parâmetros de entrada.
   Se você adicionou valores reais para os parâmetros e campos, o sistema executará esses valores no destino especificado e retornará a carga resultante. Se você mapeou variáveis de entrada para campos e parâmetros, o sistema exibirá uma caixa de diálogo para atribuir valores de teste a essas variáveis.
4. Forneça valores de teste, se solicitado, e clique em OK para exibir a carga.
   A carga inteira aparece na janela Saída bruta do formulário de Resposta.

   

5. Selecione uma das seguintes opções de mapeamento automático.
   • Mapear automaticamente para local: mapeia valores diretamente para uma variável local para uso na atividade.
   • Mapear automaticamente para saída: mapeia valores diretamente para a variável de saída para passar para outras atividades no fluxo de trabalho. O mapeamento automático para uma variável de saída cria uma matriz de objetos, cada um contendo os nomes das colunas do resultado da consulta.

Parâmetros de execução do modelo REST

Você usa parâmetros de execução para criar o script do processo de entrada no formulário de pré-processamento do designer de atividades.

Para obter descrições dos campos de comando do serviço web REST, consulte Configuração do comando de execução do REST.

Nota:

É necessário usar o prefixo executionParam. com todas as variáveis nesta tabela.

Tabela 1. Parâmetros de execução do modelo REST

Nome	Variável	Tipo	Uso
Mensagem de serviço da web	web_service_message	Referência	O sys_id da mensagem web service correspondente.
Função de mensagem de serviço da web	web_service_message_functions	Referência	O sys_id da função da mensagem REST.
Endpoint de serviço da web	web_service_endpoint	Cadeia de caracteres	URL do endpoint REST.
Parâmetros	parâmetros	Matriz de objetos JavaScript	Matriz de objetos JavaScript, expressa com o prefixo executionParam.. Para obter instruções sobre como criar matrizes usando este parâmetro, consulte Criação de uma matriz JavaScript em um modelo REST.
Usar MID Server	use_mid_server	Booliano	Seleciona se o MID Server deve ser usado ou não. Um valor verdadeiro usa o MID Server e um valor falso não usa o MID Server.
MidCapabilities	midCapabilities	Cadeia de caracteres (separados por vírgulas)	Lista de referências para os recursos MID Server exigidos
Tempo limite	time-out	Cadeia de caracteres	Duração permitida do tempo limite, expressa em segundos.
ValueCapabilities	valueCapabilities	Matriz de hashmap	Valores de recursos usados para selecionar o MID Server. Para obter mais informações, consulte Recursos do MID Server. Use este exemplo para personalizar a seleção do MID Server se houver recursos adicionais atribuídos por valor: var valueCapability = {'NEW_MID_CAPABIILTY':'NEW_MID_CAPABILITY_VALUE'}; executionParam.valueCapabilities.push(valueCapability);
Tipo de autenticação	auth-type	Booliano	Tipo de credenciais a serem usadas. As opções são: basic_auth_pick_credentials use_existing_credentials
Credenciais	credenciais	Referência	Credenciais a serem usadas para esta mensagem REST quando o auth_type selecionado for basic_auth_pick_credentials.

Criação de uma matriz JavaScript em um modelo REST

Estas são as instruções para criar matrizes JavaScript usando parâmetros de execução REST.

Antes de Iniciar

Funções necessárias: web_service_admin, activity_admin, activity_creator

Por Que e Quando Desempenhar Esta Tarefa

Para adicionar mais pares de nome-valor à matriz do parâmetro, anexe os valores à matriz existente.

Procedimento

1. Crie um objeto JavaScript com a seguinte sintaxe e adicione-o à matriz executionParam.parameter :

   var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"none"}; 
   executionParam.parameters.push(newParameter);

   Ao adicionar o novo objeto JavaScript de parâmetro à matriz, você garante que os elementos já disponíveis na matriz não sejam afetados.

2. Certifique-se de definir o valor na coluna Atributo adicional no campo de entrada Parâmetros da mensagem REST como Do not escape text.

   Nesse caso, o sistema não escapa o valor especificado para o atributo de valor. Um exemplo disso é:

   var newParameter = {"name":"parameterName","value":"parameterValue","additional_attribute":"do_not_escape_text"}; 
   executionParam.parameters.push(newParameter);

   Nota:

   Se o valor do campo additional_attribute for None, o sistema escapará do valor especificado pelo atributo value. No primeiro exemplo, parameterValue está escapado.

Parâmetros de pós-processamento do modelo REST

Use esses parâmetros para criar um script de pós-processamento.

Tabela 2. Parâmetros de pós-processamento do designer de atividades

Nome	Variável	Tipo	Uso
Código de status	status_code	Inteiro	Contém o código de status retornado do serviço web REST.
Cabeçalho	cabeçalho	Hashmap do objeto JavaScript	Hashmap de par de chave-valor associado aos valores de cabeçalho passados para o serviço web. Você pode acessar cada valor com executionResult.header[keyName].
Corpo	corpo	Cadeia de caracteres	Contém um valor de cadeia de caracteres representando a saída da mensagem REST
Erro	error	Cadeia de caracteres	Retorna a cadeia de caracteres de erro do serviço web REST, a menos que não haja erros. Nesse caso, ele retorna nulo.

Configuração do comando de execução do REST

Use as variáveis de entrada que você criou para configurar o comando que a Orquestração executa no endpoint do REST.

Antes de Iniciar

Crie as variáveis de entrada necessárias no formulário Entradas antes de avançar para a fase Comando de Execução.

Funções necessárias: web_service_admin, activity_admin, activity_creator

Nota:

Você pode testar a conexão REST entre o MID Server e o endpoint sem ter que executar a atividade em um contexto de fluxo de trabalho. Para obter detalhes, consulte saídas do modelo de teste.

Procedimento

1. Arraste as variáveis da lista de entradas e solte-as nos campos de comando.
   O sistema formata a variável na sintaxe apropriada para o comando.

   Figura 1. Comando de execução do REST

   

2. Preencha os campos exibidos na tabela.

   Tabela 3. Campos do comando de execução do REST

   Campo	Descrição
   Entrada	Construtor de variável de entrada. Criação de variáveis de entrada para mapear para campos disponíveis.
   Mensagem REST	Nome de uma mensagem REST existente a ser usada nesta atividade. Os usuários devem ter a função web_service_admin para configurar este campo.
   Função da mensagem REST	Função da mensagem REST a ser usada para esta atividade. Os usuários devem ter a função web_service_admin para configurar este campo.
   Endpoint	URL do endpoint para o serviço web REST que esta atividade usará. Insira um endpoint neste campo para substituir o endpoint configurado na mensagem REST. Clique no cadeado para abrir o campo de entrada.
   Substituições de variáveis	Pares de nome-valor a serem passados para o endpoint REST. Você pode criar esses parâmetros manualmente ou arrastar e soltar variáveis de entrada nos campos de parâmetro e então atribuir um valor. Parâmetros definidos na mensagem REST que usam $ {} podem ser dados atribuídos a partir deste modelo de atividade. Use a coluna Atributo adicional para configurar o sistema para não escapar o texto. Por padrão, o texto enviado para a mensagem REST tem escape. A coluna Nome será preenchida automaticamente se os usuários tiverem fornecido variáveis usando Substituição de variável em mensagens REST de saída na mensagem REST.
   Cabeçalhos adicionais	Parâmetros de cabeçalho HTTP adicionais para a mensagem REST selecionada. Você também pode usar esses valores para substituir parâmetros herdados da mensagem REST.
   Parâmetros de consulta adicionais	Parâmetros de consulta adicionais para a mensagem REST selecionada. Você também pode usar esses valores para substituir parâmetros herdados da mensagem REST.
   Usar MID Server	Marque a caixa que determina se um MID Server deve ser usado para invocar o serviço web REST. Nota: Se a função de mensagem do serviço web REST definir um MID Server, esse MID Server será usado em vez do selecionado aqui.
   Requer recursos do MID Server	MID Server com os recursos do MID Server apropriados para conexão com o endpoint REST. Por padrão, o sistema seleciona um MID Server que tenha o recurso REST. Este campo está disponível quando a caixa de seleção Usar MID Server está marcada.
   Tempo limite	Duração permitida da solicitação de serviço web REST em segundos antes do tempo limite. O padrão é 10.
   Autenticação	Determina que tipo de autenticação é necessária para o endpoint. As opções são: Usar credenciais existentes na mensagem REST: usa definições de credencial da definição de mensagem REST. Substituir por credenciais de autenticação básica: usa credenciais Habilitar autenticação básica para SOAP de saída para substituir as credenciais na definição de mensagem REST. As credenciais de autenticação básica devem ser provisionadas antes de ficarem disponíveis para seleção. Substituir por credenciais de autenticação de certificado: usa um certificado, como uma chave privada, para substituir as credenciais na definição de mensagem REST. Substituir por credenciais de autenticação básica e de certificado: usa tanto a autenticação básica e a por certificado para substituir as credenciais na definição de mensagem REST. Substituir por credenciais de autenticação OAuth: usa credenciais OAuth 2.0 para substituir as credenciais na definição de mensagem REST. A mensagem REST selecionada para esta atividade deve ter seu Tutorial OAuth 2.0 – criar uma mensagem REST definido como OAuth 2.0 e os perfis OAuth e escopos configurados corretamente.
   Credenciais	Requer credenciais de autenticação básicas de endpoint REST. Este campo está disponível quando Substituir por credenciais de autenticação básica é selecionado no campo Autenticação. Somente as credenciais de autenticação básica aparecem na lista de seleção, que inclui credenciais armazenadas na instância e IDs de credencial de um sistema de armazenamento externo. Se estiver usando credenciais armazenadas em um cofre CyberArk, você poderá substituir Configurar o MID Server para CyberArk definido no arquivo de configuração do MID Server adicionando o nome de um cofre diferente como um prefixo para o ID de credencial, separado por dois-pontos. Por exemplo, newsafe:orch-test-f5.
   Perfil de Protocolo	Autenticação baseada em certificados a ser usada. Este campo está disponível quando as seleções no campo Autenticação são Substituir por credenciais de autenticação de certificado ou Substituir por credenciais de autenticação básica e de certificado.
   Perfil OAuth	Perfil do provedor OAuth para esta mensagem REST. Consulte Especificação de um perfil OAuth para obter mais informações.

3. Clique em Salvar.
4. Clique em Continuar para avançar para a fase Saídas.