REST APIs

REST (Transferência de Estado Representacional) é uma arquitetura sem estado simples que fornece padrões entre sistemas de computador na Web, facilitando a comunicação entre eles.

O Now Platform fornece várias REST APIs, que estão ativas por padrão. Essas APIs fornecem a capacidade de interagir com várias funcionalidades ServiceNow em sua aplicação. Essa funcionalidade inclui a capacidade de executar operações de criação, leitura, atualização e exclusão (CRUD) em tabelas existentes (API da Tabela), inserir dados, recuperar informações e executar transformações em um banco de dados MetricBase (API MetricBase Time Series) e muitas outras.

Para obter uma lista de REST APIs disponíveis, consulte Referência de REST API.

Nota:

Você pode exibir transações de API de entrada nos logs de transações. Use um link como o abaixo para exibir as transações do dia atual:

https://<instancename>.service-now.com/syslog_transaction_list.do?sysparm_query=sys_created_onONToday%40javascript%3Ags.beginningOfToday()%40javascript%3Ags.endOfToday()%5Etype%3Drest

Formato de URI da REST e parâmetros disponíveis

ServiceNow As REST APIs seguem o protocolo padrão da REST API. Elas também fornecem URI "personalizado" e parâmetros de consulta para garantir a compatibilidade com versões anteriores e fornecer funcionalidades adicionais, como paginação de longas listas de resultados. As seções a seguir descrevem a funcionalidade por trás desses parâmetros personalizados, que são todos opcionais.

Controle de versões da REST API

ServiceNow Os URIs da REST API podem incluir um número de versão, como /api/now/v1/table/{tableName}. Os números de versão identificam a versão do endpoint que um URI acessa. Ao especificar um número de versão em seus URIs, você pode garantir que futuras atualizações da REST API não afetem negativamente sua integração.

URIs que não especificam um número de versão no URI, como /api/now/table/{tableName}, usam o endpoint REST mais recente para a versão da instância.

Métodos de solicitação HTTP compatíveis

• GET
• DELETE
• HEAD
• PATCH
• POST
• PUT

Para obter detalhes sobre esses métodos, consulte o documento RFC-2616 Hypertext Transfer Protocol.

Nota:

• Você pode usar os métodos HEAD no lugar dos métodos GET para retornar uma resposta sem um corpo de resposta.
• Você não pode passar vários registros nas operações POST, PUT e PATCH. Se você fizer isso, somente o primeiro registro será processado, o restante será ignorado.
• Você não pode usar POST, PUT e PATCH para inserir ou atualizar registros em uma exibição de banco de dados, pois as exibições de banco de dados são somente leitura.

Cabeçalhos de formato de dados

As REST APIs exigem os cabeçalhos de solicitação Accept e Content-Type para a formatação de dados adequada para solicitações que contêm um corpo de solicitação ou de resposta. As operações POST, PUT, PATCH e DELETE exigem que você forneça os dois cabeçalhos. As operações GET e HEAD exigem apenas o cabeçalho Accept. A falha em fornecer os cabeçalhos necessários resulta em um erro 400 Solicitação incorreta.

Para a maioria das REST APIs ServiceNow, esses cabeçalhos de solicitação são compatíveis com os seguintes valores:

• Aceitar: application/json, application/xml
• Content-Type: application/json, application/xml

Para obter a lista de valores específicos compatíveis com cada endpoint, consulte a referência da REST API.

Outros cabeçalhos

Todas as solicitações podem conter um cabeçalho de autenticação que especifica as credenciais do usuário a serem usadas para autenticação.

Você também pode substituir métodos HTTP, como GET ou POST, definindo o cabeçalho X-http-method-override.

Manipulação de dados especiais

A seguir, descrevemos algumas das nuanças de manipulação de dados na REST API.

• Como limpar um campo de dados: exceto para campos de opção, você pode passar um valor vazio no parâmetro para limpar o valor no banco de dados. Por exemplo, o envio de {"short description":""} limpa o campo short_description do registro especificado.
• Como os campos de moeda são tratados: os valores de moeda retornados são convertidos para a moeda local com base na localidade do usuário. Ao inserir dados, nenhuma conversão é realizada. Este comportamento se aplica a campos dos tipos Moeda ou Preço.

  Por exemplo, se um usuário na localidade do Reino Unido consultar registros com valores de moeda em USD, os valores retornados serão convertidos em GBP. No entanto, se este usuário adicionar um novo registro com o valor do campo de moeda em GBP, o valor será armazenado em GBP sem ser convertido em USD. Este valor de GBP aparece em USD se consultado por um usuário na localidade dos EUA.

• Exibição de dados da IU versus valores aprovados em um endpoint REST: a IU mostra o valor de exibiçãodo banco de dados, que são dados manipulados. Um endpoint REST, por padrão, insere e atualiza os valores reais, que podem ser diferentes do valor de exibição. Você pode forçar um endpoint REST a tratar os valores aprovados como valores de exibição, definindo o parâmetro de solicitação sysparm_input_display_value como verdadeiro.

Parâmetros de consulta personalizados

As REST APIs ServiceNow usam os seguintes parâmetros de consulta em muitas das APIs disponíveis, fornecendo um comportamento consistente nas APIs. Use esses parâmetros para paginar conjuntos de registros grandes, filtrar resultados e restringir o número de registros retornados em uma única consulta.

sysparm_limit	Número máximo de registros a serem retornados. Para solicitações que excedem esse número de registros, use o parâmetro sysparm_offset para paginar a recuperação do registro. Este limite é aplicado antes da avaliação da ACL. Se nenhum registro for retornado, incluindo os registros aos quais você tem acesso, reorganize a ordem dos registros para que os registros aos quais você tem acesso sejam retornados primeiro. Nota: Valores sysparm_limit extraordinariamente grandes podem afetar o desempenho do sistema. Tipo de dados: número Padrão: 10000
sysparm_fields	Lista separada por vírgulas de campos a serem retornados na resposta. Tipo de dados: cadeia de caracteres
sysparm_input_display_value	Sinalizador que indica se os valores de campos devem ser definidos usando o valor de exibição ou o valor real. Dependendo dos diferentes tipos de campos, o endpoint pode manipular os valores de exibição passados para armazenar os valores apropriados no banco de dados. Por exemplo, se você enviar o nome de exibição de um campo de referência, o endpoint armazenará o sys_id desse valor no banco de dados. Para campos de data e hora, quando este parâmetro é verdadeiro, o valor de data e hora é ajustado para o fuso horário do usuário atual. Quando falso, o valor de data e hora é inserido usando o fuso horário GMT. Valores válidos: verdadeiro: trata os valores de entrada como valores de exibição e eles são manipulados para que sejam armazenados corretamente no banco de dados. falso: trata os valores de entrada como valores reais e os armazena no banco de dados sem manipulação. Tipo de dados: booliano Padrão: falso - corresponde ao tipo de dados retornado durante a recuperação de dados (métodos GET), que são os valores reais. Nota: Para definir o valor de um campo criptografado, você deve definir este parâmetro como verdadeiro. Se este parâmetro não estiver definido como verdadeiro, os valores enviados para campos criptografados não serão salvos. Além disso, o usuário solicitante deve ter o contexto de criptografia apropriado antes de enviar a solicitação. Os campos criptografados ficam ocultos para usuários sem o contexto de criptografia apropriado. Para obter mais informações sobre criptografia de campo, consulte Column Level Encryption.
sysparm_offset	Índice de registro inicial para o qual a recuperação de registros será iniciada. Use este valor para paginar a recuperação do registro. Essa funcionalidade permite a recuperação de todos os registros, independentemente do número de registros, em pequenos blocos gerenciáveis. Por exemplo, na primeira vez que você chama este endpoint, sysparm_offset é definido como "0". Para simplesmente percorrer todos os registros disponíveis, use sysparm_offset=sysparm_offset+sysparm_limitaté chegar ao fim de todos os registros. Não passe um número negativo no parâmetro sysparm_offset. Tipo de dados: número Padrão: 0
sysparm_query	Consulta codificada usada para filtrar o conjunto de resultados. Você pode usar um filtro de IU para obter uma consulta codificada corretamente. Sintaxe: sysparm_query=<col_name><operator><value> . <col_name>: Nome da coluna da tabela para filtrar. <operator>: oferece suporte aos seguintes valores: =: Corresponde exatamente a<value> . !=: não corresponde<value> . ^: logicamente E várias declarações de consulta. ^OR: logicamente OU várias declarações de consulta. CURTIR:<col_name> contém a cadeia de caracteres especificada. Só funciona para<col_name> campos cujo tipo de dados é cadeia de caracteres. COMEÇA COM:<col_name> começa com a cadeia de caracteres especificada. Só funciona para<col_name> campos cujo tipo de dados é cadeia de caracteres. TERMINACOM:<col_name> termina com a cadeia de caracteres especificada. Só funciona para<col_name> campos cujo tipo de dados é cadeia de caracteres. <value>: valor a ser correspondido. Todos os parâmetros fazem distinção entre maiúsculas e minúsculas. As consultas podem conter mais de uma entrada, como sysparm_query=<col_name><operator><value> [ ] . Por exemplo: (sysparm_query=caller_id=javascript:gs.getUserID()^active=true) As consultas codificadas também oferecem suporte à ordem por funcionalidade. Para classificar respostas com base em determinados campos, use as cláusulas ORDERBY e ORDERBYDESC em sysparm_query. Sintaxe: ORDERBY<col_name> ORDERBYDESC<col_name> Por exemplo: sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory Esta consulta filtra todos os registros ativos e ordena os resultados em ordem crescente por número e, em seguida, em ordem decrescente por categoria. Se parte da consulta for inválida, por exemplo, especificando um nome de campo inválido, a instância ignorará a parte inválida. Em seguida, ele retorna linhas usando somente a parte válida da consulta. Você pode controlar esse comportamento usando a propriedade glide.invalid_query.returns_no_rows. Defina esta propriedade como verdadeira para não retornar linhas em uma consulta inválida. Nota: A propriedade glide.invalid_query.returns_no_rows controla o comportamento de todas as consultas na instância, como em listas, scripts (GlideRecord.query()) e APIs de serviço web. Tipo de dados: cadeia de caracteres
sysparm_view	Exibição de IU para a qual os dados serão renderizados. Determina os campos retornados na resposta. Valores válidos: área de trabalho para celular ambos Se você também especificar o parâmetro sysparm_fields, ele terá precedência. Tipo de dados: cadeia de caracteres

Referência com pontos em solicitações de REST API

Você pode usar a referência com pontos ao especificar os parâmetros sysparm_query ou sysparm_fields em solicitações para REST APIs compatíveis com esses parâmetros.

Nota:

A API do Import Set não é compatível com a referência com pontos.

Referência com pontos em sysparm_query

Você pode filtrar consultas usando valores de registros relacionados ao fazer a referência com pontos no parâmetro sysparm_query. Por exemplo, você pode recuperar todos os registros de incidentes em que a Empresa do incidente tem um valor de Símbolo de ação específico.

https://<instance>.service-now.com/api/now/table/incident?sysparm_query=company.stock_symbol=NYX

Referência com pontos no sysparm_fields

Você pode exibir valores de campos de várias tabelas fazendo referência com pontos no parâmetro sysparm_fields. Por exemplo, você pode recuperar o Nome, o Sys_id e o Departamento de cada usuário que tenha determinadas funções, bem como a função Nome.

A solicitação é executada na tabela Funções do usuário [sys_user_has_role] que define um relacionamento muitos para muitos entre usuários e funções. A resposta inclui valores de campos das tabelas Usuário [sys_user] e Funções [sys_user_role].

https://<instance>.service-now.com/api/now/table/sys_user_has_role?sysparm_fields=role%2Crole.name%2Cuser%2Cuser.name%2Cuser.sys_id%2Cuser.department&sysparm_query=role%3D3d43716d0f6002003a2d47bce1050e0d%5EORrole%3Dac73b52d0f6002003a2d47bce1050eec&sysparm_display_value=true

{
"result": [
  {
   "user.name": "Fred Johnson",
   "user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
   "role.name": "support",
   "user.department": {
      "display_value": "Accounting",
      "link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
    },
   "role": {
      "display_value": "support",
      "link": "https://<instance>.service-now.com/api/now/table/sys_user_role/3d43716d0f6002003a2d47bce1050e0d"
    },
   "user": {
      "display_value": "Fred Johnson",
      "link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
    }
  },
  {
   "user.name": "Fred Johnson",
   "user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
   "role.name": "asset_mgmt",
      "user.department": {
      "display_value": "Accounting",
      "link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
     },
    "role": {
       "display_value": "asset_mgmt",
       "link": "https://<instance>.service-now.com/api/now/table/sys_user_role/ac73b52d0f6002003a2d47bce1050eec"
      },
    "user": {
       "display_value": "Fred Johnson",
       "link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
       }
    }
  ]
}

Códigos de resposta HTTP da REST API

As chamadas feitas para endpoints REST retornam códigos de resposta HTTP. Você pode usar esses códigos de resposta para garantir que a REST API foi executada corretamente. Caso contrário, o endpoint retornará um código de resposta de erro. Use as informações na resposta de erro para solucionar problemas com o formato da chamada. Para obter uma lista de códigos de resposta padrão que um endpoint pode retornar, consulte Códigos de resposta HTTP da REST API. Para obter a lista de códigos de resposta retornados por uma REST API ServiceNow específica, consulte a referência da REST API.

Segurança da REST API

Por padrão, REST APIs ServiceNow usam autenticação básica ou OAuth para autorizar o acesso do usuário a REST APIs/endpoints. Você também pode configurar sua instância para usar autenticação multifator para acessar REST APIs.

A ID do usuário que você especifica em uma chamada de endpoint REST está sujeita ao controle de acesso da mesma forma que um usuário interativo. Cada solicitação requer as informações de autenticação apropriadas, como nome de usuário e senha. Certifique-se de que cada solicitação de endpoint inclua um cabeçalho de autorização com credenciais suficientes para acessar o endpoint.

As REST APIs ServiceNow também oferecem suporte a cookies que permitem a vinculação à sessão existente.

Para usar o certificado para chamar a API e informações sobre autenticação mútua, consulte Autenticação baseada em certificados.

A REST API acessa políticas com os critérios de filtro como IP, função e grupo, e restringe o escopo da API que você pode usar com o REST API Auth Scope. Para saber mais sobre a política de acesso à REST API, consulte Políticas de acesso à REST API.

Você pode criar uma única política para bloquear a solicitação de entrada, em um nível de REST API global, usando a política de acesso de REST API de uma rede confiável externa e em níveis de autenticação REST básicos.

Funções da REST API

Além da autenticação de usuário, cada endpoint REST pode ter requisitos diferentes para as funções necessárias para acessar o endpoint. Alguns exigem a função de administrador e outros exigem funções específicas de API. Os requisitos de função são especificados na lista de controle de acesso (ACL) associada à REST API/endpoint. Para obter detalhes sobre as funções válidas para cada REST API/endpoint, consulte a referência da REST API ou localize a ACL associada para a API/endpoint em uma instância em System Security > Controle de acesso (ACL).

ACLs da REST API

As ACLs da REST API definem critérios, como as funções necessárias e as condições que um usuário deve atender para acessar uma REST API ServiceNow ou endpoint. Uma única ACL pode ser definida para uma REST API inteira, como a API da tabela e as ACLs da API de anexos, ou para um endpoint individual, como a ACL clotho_rest_put que se aplica somente a métodos PUT MetricBase.

As seguintes ACLs ServiceNow de REST API estão disponíveis no sistema de base, mas são desativadas por padrão. Todas as outras ACLs ServiceNow da REST API estão ativas por padrão.

• API da tabela
• API agregada
• API do Import Set
• API de anexos

Para obter informações adicionais sobre ACLs, consulte Regras da lista de controle de acesso.

Importante:

Você nunca deve modificar os nomes das ACLs da REST API.

Acesso à tabela da REST API

Por padrão, todas as tabelas, incluindo tabelas do sistema base, tabelas globais e tabelas com escopo, podem ser acessadas por meio de serviços Web. Você deve atender a todos os requisitos de segurança de serviço da Web, como autenticação básica e ACLs para acessar tabelas por meio de serviços Web. Os campos para os quais a entidade que faz a chamada não tem direitos devido às ACLs não são retornados em uma resposta de consulta REST.

Para permitir o acesso a tabelas sem qualquer autenticação ou autorização, adicione o nome da tabela à tabela Páginas públicas [sys_public] com um status Ativo. A interface REST ainda impõe todas as ACLs definidas nas tabelas associadas. Se a imposição de ACL não for o comportamento desejado, você deverá desativar as ACLs nas tabelas. No entanto, tornar suas APIs públicas não é sugerido, pois isso permite que o acesso público atualize os dados na instância.

Você também pode controlar o acesso direto ao serviço Web a tabelas usando a caixa de seleção Permitir acesso a esta tabela por meio de serviços Web nas configurações de acesso à aplicações de tabela. Você deve marcar esta caixa de seleção para habilitar a interação do serviço Web com a tabela.

Nota:

Os campos de acesso à aplicação que controlam as operações CRUD, como Pode ler ou Pode criar não se aplicam a solicitações de serviços Web.

Autenticação multifator para REST de entrada

Quando a autenticação multifator está habilitada para uma conta de usuário, você deve enviar um token de MFA com credenciais de autenticação básica ao fazer solicitações REST como esse usuário.

Para enviar um token de MFA com uma solicitação REST, anexe o token ao final da senha do usuário na cadeia de caracteres username:password de autenticação básica, como joe.employee:password62161147. Codifique a cadeia de caracteres completa, incluindo o token de MFA, usando a codificação base64 e, em seguida, envie a cadeia de caracteres codificada no cabeçalho de autorização.

Respostas RESTs de autenticação multifator

A resposta a uma solicitação de autenticação de MFA varia de acordo com a validade das credenciais fornecidas e o token de MFA.

Tabela 1. Respostas

Resultado	Descrição
As credenciais de autenticação básica e o token de MFA são válidos	O usuário é autenticado e a sessão criada. A solicitação é processada normalmente.
As credenciais de autenticação básica são válidas, mas o token de MFA é inválido ou está ausente	A resposta retorna o erro 401. A resposta inclui o cabeçalho X-MFA_TOKEN com o valor inválido.
As credenciais de autenticação básica são inválidas	A resposta retorna o erro 401. O cabeçalho X-MFA_TOKEN não está incluído na resposta.

Suporte a REST API CORS

A REST API oferece suporte à segurança de compartilhamento de recursos de origem cruzada (CORS). O suporte ao CORS permite que você defina quais domínios podem acessar cada REST API. Ao definir uma regra CORS para um domínio, você pode permitir solicitações de origem cruzada a partir desse domínio. As solicitações de origem cruzada não podem ser feitas a partir de domínios sem uma regra CORS.

Nota:

O suporte a CORS se aplica somente a REST APIs, incluindo serviços Web REST com script. Outras APIs de serviço da Web, como a API SOAP, não são compatíveis com CORS.

Você pode configurar o CORS para permitir acesso somente a determinados APIs/endpoints, métodos HTTP e cabeçalhos de outros domínios. Por exemplo, você pode limitar as solicitações à API da tabela de um domínio específico para permitir somente operações GET.

Para exibir as regras CORS definidas em sua instância, navegue até Serviços web do sistema > Regras CORS.

Você pode desabilitar o suporte a CORS para uma instância definindo a propriedade glide.rest.cors.enabled como falso. Quando falso, nenhuma avaliação CORS é realizada em solicitações REST de entrada. Essa propriedade será definida como verdadeira por padrão.

Explorador de REST API

O Explorador de REST API é uma ferramenta ServiceNow que usa informações da sua instância para fornecer uma lista de endpoints, métodos e variáveis que você pode usar para criar e enviar solicitações REST.

Depois de criar a solicitação, o Explorador de REST API fornece amostras de código em várias linguagens de programação que você pode usar para iniciar a solicitação, além de informações detalhadas de solicitação e resposta.

Para acessar o Explorador de REST API, em sua instância, navegue até Serviços web do sistema > Explorador de REST API. Você deve ter a função rest_api_explorer para acessar o Explorador de REST API. Para obter informações adicionais, consulte Usar o Explorador de REST API.

Aviso:

O Explorador de REST API interage com os dados na instância atual. Tenha cuidado ao trabalhar com solicitações que criam, editam ou excluem dados em uma instância de produção.

Suporte ao Automated Test Framework

O Automated Test Framework (ATF) oferece suporte às etapas de teste REST de entrada. Você pode criar testes automatizados para as REST APIs de entrada personalizadas que você cria. Criar testes para suas REST APIs personalizadas simplifica o teste de atualização e possibilita verificar se as modificações em uma REST API são compatíveis com versões anteriores.

Exemplo de aplicações cliente REST

Vários exemplos de aplicações cliente REST e código de origem estão disponíveis para demonstrar integrações usando serviços Web REST. O exemplo de aplicações cliente REST demonstra como usar a REST API ServiceNow com um aplicativo externo, como um aplicativo NodeJS ou iOS.

Importante:

Essas aplicações são fornecidas apenas como uma demonstração da funcionalidade REST e não são oficialmente compatíveis.

Os exemplos são de código aberto e estão disponíveis para a comunidade. Você pode usar essas aplicações de exemplo para ajudar a se familiarizar com a funcionalidade REST ou usá-las como ponto de partida para criar suas próprias aplicações cliente REST.

Usuários com a função rest_api_explorer podem acessar a lista de aplicações cliente disponíveis navegando até Serviços web do sistema > REST > Exemplo de aplicações cliente.

Ao exibir a lista de aplicações, clique em uma aplicação para exibir o código de origem e a documentação adicional hospedada no GitHub.

Desenvolver treinamento

No ServiceNow® Site do desenvolvedor, você pode obter treinamento para Integrações REST de entrada e Integrações REST de saída.

Informações adicionais

O restante da seção REST API contém tópicos de "como fazer" que descrevem implementações específicas usando a REST API ServiceNow e fornece informações de referência que descrevem vários elementos de dados usados pela REST API ServiceNow.

• Use o Explorador de REST API
  Neste tutorial, você usará o Explorador de REST API para testar as REST APIs ServiceNow.
• Limitação de taxa da REST API de entrada
  Para evitar solicitações de REST API de entrada excessivas, defina regras que limitem o número de solicitações de REST API de entrada processadas por hora. Você pode criar regras para limitar as solicitações de usuários específicos, usuários com funções específicas ou todos os usuários.
• Depurar consultas REST de entrada
  Você pode depurar consultas REST de entrada revisando o log de depuração da sessão.
• Retornar logs de depuração de sessão em uma resposta REST
  Você pode incluir logs de depuração de sessão em um corpo de resposta REST passando o cabeçalho X-WantSessionDebugMessages na solicitação.
• Requisitos de domínio CORS
  Quando você define uma regra de compartilhamento de recursos de origem cruzada (CORS), o valor inserido no campo Domínio deve atender a determinados requisitos. Cada regra CORS oferece suporte a um único caractere curinga para corresponder aos cabeçalhos de origem de entrada.
• Definir uma regra CORS
  Você pode definir uma regra CORS para controlar quais domínios podem acessar endpoints de REST API e outros recursos da Web.
• Habilitar OAuth com REST de entrada
  Usando o OAuth, você pode passar um ID de usuário e senha uma vez e, em seguida, usar um token para solicitações REST subsequentes em vez de enviar credenciais com cada solicitação.
• Códigos de resposta HTTP da REST API
  As mensagens REST enviadas para uma instância retornam um código de resposta HTTP específico.
• Scripted REST APIs
  O recurso de API REST de script permite que os desenvolvedores de aplicações criem APIs de serviço web personalizadas.

Tópicos relacionados

• Perguntas frequentes da REST API