REST APIs

REST (Representational State Transfer) é uma arquitetura simples sem estado que fornece padrões entre sistemas de computador na web, facilitando a comunicação entre eles.

. Now PlatformFornece várias APIs REST, que estão ativas por padrão. Essas APIs fornecem a capacidade de interagir com vários ServiceNowem 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 ( Tabela API), inserir dados em, recuperar informações de e executar transformações em um banco de dados MetricBase ( MetricBase Time Series E muitos outros.

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

Nota:

Você pode exibir transações de API de entrada nos logs de transação. 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

REST URI e parâmetros disponíveis

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

REST API

ServiceNowREST API podem incluir um número de versão, como /api/now/v1/table/ . 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 na 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/ , Use 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 Protocolo de transferência de hipertexto RFC-2616 documento.

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 em operações DE POST, PUT e PATCH. Se você fizer isso, somente o primeiro registro será processado, o restante será ignorado.
• Não é possível 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

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

Para a maioria ServiceNowREST APIs Esses cabeçalhos de solicitação são compatíveis com os seguintes valores:

• Aceitar: application/json, application/xml
• Tipo de conteúdo: application/json, application/xml

Para obter a lista de valores específicos compatíveis com cada endpoint, consulte 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. X-http-method-overridecabeçalho.

Tratamento especial de dados

A seguir descreve algumas das nuances de manipulação de dados na REST API.

• Como limpar um campo de dados: Exceto para campos de escolha, você pode passar um valor vazio no parâmetro para limpar o valor no banco de dados. Por exemplo, enviando "descrição resumida":""" limpa o. short_descriptioncampo 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 em GBP aparece em USD se consultado por um usuário na localidade dos EUA.

• Exibição de dados de IU versus valores passados em um endpoint REST: A IU mostra o banco de dados valor de exibição , 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 valores passados como valores de exibição definindo o. sysparm_input_display_value parâmetro de solicitação como verdadeiro.

Parâmetros de consulta personalizados

. ServiceNowAs REST APIs usam os seguintes parâmetros de consulta em muitas das APIs disponíveis, fornecendo comportamento consistente em todas as 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 sysparm_offsetparâmetro para paginar a recuperação de registro. Este limite é aplicado antes da avaliação da ACL. Se nenhum registro retornar, incluindo registros aos quais você tem acesso, reorganize a ordem de registro para que os registros que você tenha acesso para retornar primeiro. Nota: Excepcionalmente grande sysparm_limitos valores podem afetar o desempenho do sistema. Tipo de dados: Número Padrão: 20 Máximo: 100
sysparm_fields	Lista separada por vírgulas de campos a serem retornados na resposta. Campos inválidos são ignorados. Tipo de dados: Cadeia de caracteres Padrão: Retornar todos os campos.
sysparm_input_display_value	Sinalizador que indica se valores de campo 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 for verdadeiro, o valor de data e hora será 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 DE OBTENÇÃO), que são os valores reais. Nota: Para definir o valor de um campo criptografado, defina 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 estão ocultos para usuários sem o contexto de criptografia apropriado. Para obter mais informações sobre criptografia de campo, consulte Encryption.
sysparm_offset	Índice de registro inicial para o qual iniciar a recuperação de registros. Use este valor para paginar a recuperação de registro. Esta 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ê chamar este endpoint, sysparm_offsetestá definido como "0". Para simplesmente percorrer todos os registros disponíveis, use se você deseja usar o sysparm_offset, você pode usar o sysparm_limit , até chegar ao final de todos os registros. Não passe um número negativo em sysparm_offsetparâmetro. Tipo de dados: Número Padrão: 0
sysparm_query	Consulta codificada usado para filtrar o conjunto de resultados. Você pode usar um filtro de IU para obter uma consulta codificada corretamente. Sintaxe: <col_name> <operator> <value> . <col_name>: Nome da coluna da tabela a ser filtrada. <operator>: É compatível com os seguintes valores: : Corresponde exatamente ao <value>. : Não corresponde ao <value>. Declarações de consulta lógica E múltipla. OU: Declarações de consulta lógica OU múltipla. LIKE: <col_name> contém a cadeia de caracteres especificada. Funciona somente para campos <col_name> cujo tipo de dados é cadeia de caracteres. STARTSWITH: O <col_name> começa com a cadeia de caracteres especificada. Funciona somente para campos <col_name> cujo tipo de dados é cadeia de caracteres. ENDSWITH: O <col_name> termina com a cadeia de caracteres especificada. Funciona somente para campos <col_name> cujo tipo de dados é cadeia de caracteres. <value>: Valor a ser correspondido. Todos os parâmetros diferenciam maiúsculas de minúsculas. As consultas podem conter mais de uma entrada, como <col_name> <operator> <value>[<operator> <col_name> <operator> <value>] . Por exemplo: (Sysparm_query As consultas codificadas também são compatíveis com a funcionalidade ordenar por. Para classificar respostas com base em determinados campos, use POR PEDIDO e. DESC cláusulas em sysparm_query. Sintaxe: ORDERBY<col_name> ORDERBYDESC<col_name> Por exemplo: Se você deseja usar o SYSPARM_QUERY 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, retorna linhas usando apenas 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: . glide.invalid_query.returns_no_rowsa propriedade 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: desktop móvel ambos Se você também especificar o. sysparm_fieldsparâmetro, ele tem precedente. Tipo de dados: Cadeia de caracteres

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

Você pode usar a referência com pontos ao especificar sysparm_queryou sysparm_fieldsParâmetros em solicitações para APIs REST que oferecem suporte a esses parâmetros.

Nota:

A API do conjunto de importação não é compatível com referência com pontos.

Referência com pontos em sysparm_query

Você pode filtrar consultas usando valores de registro relacionados colocando pontos no sysparm_queryparâmetro. Por exemplo, você pode recuperar todos os registros de incidente em que o incidente ocorreu Empresa tem um específico Símbolo da ação valor.

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

Referência com pontos em sysparm_fields

Você pode exibir valores de campo de várias tabelas colocando pontos no sysparm_fieldsparâmetro. Por exemplo, você pode recuperar o. Nome , Sys_id e. Departamento de cada usuário que tem determinadas funções, bem como a função Nome .

A solicitação é executada na tabela Funções de usuário [sys_user_has_role], que define um relacionamento muitos para muitos entre usuários e funções. A resposta inclui valores de campo 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"
       }
    }
  ]
}

REST API códigos de resposta HTTP

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 seja 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 de chamada. Para obter uma lista de códigos de resposta padrão que um endpoint pode retornar, consulte REST API códigos de resposta HTTP. Para obter a lista de códigos de resposta retornados por um específico ServiceNowREST API, consulte REST API .

REST API

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

O ID de usuário que você especifica em uma chamada de endpoint REST está sujeito ao controle de acesso da mesma forma que um usuário interativo. Cada solicitação requer as informações de autenticação adequadas, 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.

ServiceNow REST APIs também são compatíveis com cookies que permitem a vinculação à sessão existente.

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

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

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

REST API

Além da autenticação do 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 da 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 REST API Ou localize a ACL associada à API/endpoint em uma instância por meio de Segurança do sistema > Controle de acesso (ACL) .

REST API

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

O seguinte ServiceNowREST API ACLs estão disponíveis no sistema base, mas são desativadas por padrão. Todos os outros ServiceNowREST API estão ativas por padrão.

• API da tabela
• API agregada
• API do conjunto de importação
• API de anexo

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.

REST API acesso à tabela

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

Para permitir acesso a tabelas sem autenticação ou autorização, adicione o nome da tabela à tabela Páginas públicas [sys_public] com 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 porque isso permite que o acesso público atualize dados na instância.

Você também pode controlar o acesso direto ao serviço web a tabelas usando o. Permita acesso a esta tabela por meio de serviços da web na tabela configurações de acesso à aplicação. 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 de CRUD, como Pode ler ou Pode criar não se aplicam a solicitações de serviço web.

Autenticação multifator para REST DE entrada

A partir da versão de Yokohama, a autenticação multifator (MFA) não é necessária por padrão para a autenticação da API REST usando autenticação básica. Para saber mais, veja isso artigo da base de conhecimento .

Respostas REST de autenticação multifator

A resposta a uma solicitação de autenticação de MFA varia dependendo da validade das credenciais fornecidas e do token de MFA.

Tabela 1. Respostas

Resultado	Descrição
As credenciais de autenticação básicas 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ásicas 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ásicas são inválidas	A resposta retorna o erro 401. O cabeçalho X-mfa_TOKEN não está incluído na resposta.

REST API COMPATÍVEL COM CORS

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

Nota:

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

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

Para exibir as regras de 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 o. glide.rest.cors.enabledpropriedade para falso . Quando falso Nenhuma avaliação de CORS é realizada nas solicitações REST de entrada. Essa propriedade será definida como verdadeira por padrão.

Explorador de REST API

O Explorador da REST API é um ServiceNowFerramenta 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 da REST API fornece exemplos 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 da 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 da REST API. Para obter informações adicionais, consulte Use o Explorador da REST API .

Aviso:

O Explorador da 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 à estrutura de testes automatizados

A Estrutura de testes automatizados (ATF) oferece suporte a etapas de teste REST de entrada. Você pode criar testes automatizados para APIs REST de entrada personalizadas que você criar. A criação de testes para APIs REST personalizadas simplifica o teste de upgrade e possibilita verificar se as modificações em uma REST API são compatíveis com versões anteriores.

Aplicações de cliente REST de exemplo

Vários exemplos de aplicações de cliente REST e código-fonte estão disponíveis para demonstrar integrações usando serviços web REST. As aplicações de cliente REST de exemplo demonstram como usar o. ServiceNowREST API com uma aplicação externa, como uma aplicação 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 esses exemplos de aplicações para se familiarizar com a funcionalidade REST ou usá-los como ponto de partida para criar suas próprias aplicações cliente REST.

Os 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-fonte e a documentação adicional hospedada no GitHub.

Desenvolver treinamento

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

Informação adicional

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

• Use o Explorador da REST API
  Neste tutorial, você usará o Explorador da REST API para testar o. ServiceNowREST APIs.
• Limitação de taxa da API REST de entrada
  Para evitar solicitações excessivas de API REST de entrada, defina regras que limitem o número de solicitações de API REST de entrada processadas por hora. Você pode criar regras para limitar 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.
• Retorne logs de depuração da 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 do CORS
  Quando você define uma regra de compartilhamento de recursos entre origens (CORS), o valor inserido no Domínio o campo deve atender a determinados requisitos. Cada regra de CORS oferece suporte a um único curinga para corresponder aos cabeçalhos de origem de entrada.
• Defina uma regra de CORS
  Você pode definir uma regra de CORS para controlar quais domínios podem acessar endpoints da REST API e outros recursos da web.
• Habilite OAuth com REST DE entrada
  Usando o OAuth, você pode passar um ID de usuário e senha uma vez e usar um token para solicitações REST subsequentes em vez de enviar credenciais com cada solicitação.
• REST API códigos de resposta HTTP
  As mensagens REST enviadas para uma instância retornam um código de resposta HTTP específico.
• Scripted REST APIs
  O recurso REST API com script permite que os desenvolvedores de aplicações criem APIs de serviço web personalizadas.

Tópicos relacionados

• REST API