REST APIs

O ServiceNow AI 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 sysparm_offsetparâmetro para paginar a recuperação de 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 do registro para que os registros que você tenha acesso sejam retornados primeiro. Nota: Incomum 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 para 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 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 começar a recuperar 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_offsetdefinido como "0". Para simplesmente percorrer todos os registros disponíveis, use `se você não tiver certeza de que você está usando o sysparm_offset` 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: `sysparm_query_query_<col_name> <operator> <value>` . <col_name>: Nome da coluna da tabela a ser filtrada. Compatível com os seguintes valores <operator>: 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. CURTIR: O <col_name> contém a cadeia de caracteres especificada. Funciona somente para campos do <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 do <col_name> cujo tipo de dados é cadeia de caracteres. ENDSWITH: O <col_name> termina com a cadeia de caracteres especificada. Funciona somente para campos do <col_name> cujo tipo de dados é cadeia de caracteres. <value>: Valor a ser correspondido. Para obter mais operadores, consulte Operators available for filters and queries. Todos os parâmetros diferenciam maiúsculas de minúsculas. As consultas podem conter mais de uma entrada, como `sysparm_query_<col_name> <operator> <value>[<operator> <col_name> <operator> <value>]` . Por exemplo: `(Sysparm_query_caller_id_id_javascript:gs.getUserID() "ative_true")` As consultas codificadas também são compatíveis com a funcionalidade Ordem por. Para classificar respostas com base em determinados campos, use `ORDERBY` e. `ORDERBYDESC` cláusulas em sysparm_query. Sintaxe: `ORDERBY<col_name>` `ORDERBYDESC<col_name>` Por exemplo: `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, como especificar 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: . 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 sysparm_fieldsparâmetro, ele tem precedente. 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 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 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

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

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 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 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.