REST API com script - ServiceNow Fluent

A REST API com script define os endpoints, parâmetros de consulta e cabeçalhos de um serviço REST com script [sys_ws_definition].

Para obter informações gerais sobre serviços REST com script, consulte Scripted REST APIs.

Conceitos relacionados

• ServiceNow Fluent

Objeto RestApi

Crie uma REST API com script [sys_ws_definition] para definir endpoints de serviço web.

Tabela 1. Propriedades

Nome	Tipo	Descrição
id	Cadeia de caracteres ou número	Necessário. Um ID exclusivo para o objeto de metadados. Quando você cria a aplicação, este ID é hash em um sys_id exclusivo. Para obter mais informações, consulte ServiceNow Fluent construções de linguagem. Formato: Now.ID['Cadeia de caracteres' ou número]
nome	Cadeia de caracteres	Necessário. O nome da API, que é usado na documentação da API.
serviceId	Cadeia de caracteres	Necessário. O identificador de API usado para distinguir esta API em caminhos de URI. Ele deve ser exclusivo no namespace da API.
ativo	Booliano	Sinalizador que indica se a API pode atender solicitações. Valores válidos: Verdadeiro: A API pode atender solicitações. Falso: A API não pode atender solicitações. Padrão: verdadeiro
shortDescription	Cadeia de caracteres	Uma breve descrição da API, que é usada na documentação da API.
consome	Cadeia de caracteres	Uma lista de tipos de mídia que os recursos da API podem consumir. Padrão: Application/json,application/xml,text/xml
DocLink	Cadeia de caracteres	Um URL vinculado à documentação estática sobre a API.
Excetividade	Matriz	Uma lista de identificadores de variáveis de ACL Objetos ou sys_ids de ACLs a serem aplicados ao acessar recursos [sys_security_acl]. Para obter mais informações, consulte API da lista de controle de acesso - ServiceNow Fluent. Para não impor ACLs, defina esta propriedade como uma matriz vazia ( [] ). Padrão: REST externo com script padrão
produz	Cadeia de caracteres	Uma lista de tipos de mídia que os recursos da API podem produzir. Padrão: Application/json,application/xml,text/xml
rotas	Matriz	Os recursos [sys_ws_operation] da API. Para obter mais informações, consulte objeto de rotas.
política	Cadeia de caracteres	A política de como os arquivos da aplicação são protegidos quando baixados ou instalados. Valores válidos: Leitura: Os arquivos são visíveis somente. Protegido: Usuários com permissões de senha podem editar os arquivos.
versões	Matriz	Uma lista de versões [sys_ws_version] da API. Para obter mais informações, consulte objeto de versões. A especificação de versões permite gerenciar diferentes versões de uma API e seus status, como se elas estão ativas, a versão padrão ou obsoletas.
meta	Objeto	Metadados dos metadados da aplicação. Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas. $meta: {       installMethod: 'String' } Valores válidos para Método de instalação : Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada. Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.

import { RestApi } from '@servicenow/sdk/core'
import { process } from '../server/handler.js'

RestApi({
    $id: Now.ID['rest1'],
    name: 'customAPI',
    serviceId: 'custom_api',
    consumes: 'application/json',
    routes: [
        {
            $id: Now.ID['route1'],
            path: '/home/{id}',
            script: process,
            parameters: [{ $id: Now.ID['param1'],  name: 'n_param' }],
            headers: [{ $id: Now.ID['header1'],  name: 'n_token' }],
            enforceAcl: [acl],
            version: 1,
        },
    ],
    enforceAcl: [acl],
    versions: [
        {
            $id: Now.ID['v1'],
            version: 1,
        },
    ],
})

A ACL referenciada é definida usando ACL objeto:

import { Acl } from "@servicenow/sdk/core";

const acl = Acl({
    name: 'My random ACL',
    type: 'rest_endpoint',
    script: `answer = (Math.random() > 0.5)`,
    active: true,
    adminOverrides: false,
    operations: ['execute'],
})

objeto de rotas

Crie um recurso REST com script [sys_ws_operation] para definir o método HTTP, o script de processamento e substituir as configurações do serviço primário.

Use o. rotas objeto em RestApi objeto.

Tabela 2. Propriedades

Nome	Tipo	Descrição
id	Cadeia de caracteres ou número	Necessário. Um ID exclusivo para o objeto de metadados. Quando você cria a aplicação, este ID é hash em um sys_id exclusivo. Para obter mais informações, consulte ServiceNow Fluent construções de linguagem. Formato: Now.ID['Cadeia de caracteres' ou número]
nome	Cadeia de caracteres	O nome do recurso da API, que é usado na documentação da API. Padrão: O valor de caminho propriedade
script	Script	Necessário. O script personalizado define como a operação analisa e responde às solicitações. Esta propriedade é compatível com uma função de um módulo JavaScript, uma referência a outro arquivo na aplicação que contém um script ou JavaScript em linha. Formato: Para funções, use o nome de uma função, expressão de função ou função padrão exportada de um módulo JavaScript e importe-a para o. .now.ts arquivo. Para obter informações sobre módulos JavaScript, consulte Módulos JavaScript e bibliotecas de terceiros. Para usar conteúdo de texto de outro arquivo, consulte um arquivo na aplicação usando o seguinte formato: Now.include('path/to/file') . Para obter mais informações, consulte ServiceNow Fluent construções de linguagem. Para fornecer um script em linha, use literais de cadeia de caracteres ou literais de modelo para várias linhas de código: "Script" ou "Script" .
parâmetros	Matriz	Uma lista de parâmetros de consulta [sys_ws_query_parameter] para a rota. Para obter mais informações, consulte objetos de parâmetros e cabeçalhos.
cabeçalhos	Matriz	Uma lista de cabeçalhos [sys_ws_header] da rota. Para obter mais informações, consulte objetos de parâmetros e cabeçalhos.
ativo	Booliano	Sinalizador que indica se o recurso é usado. Valores válidos: Verdadeiro: O recurso é usado. Falso: O recurso não é usado. Padrão: verdadeiro
caminho	Cadeia de caracteres	O caminho do recurso relativo ao caminho da API base. O URI relativo pode conter parâmetros de caminho, como '/abc/id' . Padrão: /
shortDescription	Cadeia de caracteres	Uma breve descrição do recurso, que é usado na documentação da API.
consome	Cadeia de caracteres	Uma lista de tipos de mídia que o recurso pode consumir. Esta propriedade pode ser substituída pelos métodos PUT, PATCH ou POST. Padrão: O valor de consome propriedade em RestApi objeto
Excetividade	Matriz	Uma lista de identificadores de variáveis de ACL Objetos ou sys_ids de ACLs a serem aplicados ao acessar recursos [sys_security_acl]. Para obter mais informações, consulte API da lista de controle de acesso - ServiceNow Fluent. Para não impor ACLs, defina esta propriedade como uma matriz vazia ( [] ). Padrão: REST externo com script padrão
produz	Cadeia de caracteres	Uma lista de tipos de mídia que o recurso pode produzir. Padrão: O valor de produz propriedade em RestApi objeto
ExampleSolicitação	Cadeia de caracteres	Uma carga de corpo de solicitação de amostra válida para o recurso, que é usada na documentação da API.
method	Cadeia de caracteres	O método HTTP implementado pelo recurso. Valores válidos: GET, POST, PUT, PATCH, DELETE Padrão: OBTER
autorização	Booliano	Sinalizador que indica se os usuários devem ser autenticados para acessar o recurso. Valores válidos: Verdadeiro: Os usuários devem ser autenticados para acessar o recurso. Falso: A autenticação não é necessária para acessar o recurso. Padrão: verdadeiro
autenticação	Booliano	Sinalizador que indica se as ACLs são impostas ao acessar o recurso. Valores válidos: Verdadeiro: As ACLs são impostas ao acessar o recurso. Falso: As ACLs não são impostas ao acessar o recurso. Padrão: verdadeiro
InternalRole	Booliano	Sinalizador que indica se a rota requer a função snc_internal. Esta propriedade será compatível somente se o plug-in de funções explícitas (com.glide.explicit_roles) estiver habilitado. Valores válidos: Verdadeiro: A rota requer a função snc_internal. Falso: A rota não requer a função snc_internal. Padrão: verdadeiro
política	Cadeia de caracteres	A política de como os arquivos da aplicação são protegidos quando baixados ou instalados. Valores válidos: Leitura: Os arquivos são visíveis somente. Protegido: Usuários com permissões de senha podem editar os arquivos.
versão	Número	A versão da API. Esta propriedade será necessária se versões a propriedade é usada em RestApi objeto. A versão especificada com esta propriedade é usada para gerar automaticamente um URI com uma versão, como /api/management/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, você pode testar e implantar mudanças sem afetar as integrações existentes.
meta	Objeto	Metadados dos metadados da aplicação. Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas. $meta: {       installMethod: 'String' } Valores válidos para Método de instalação : Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada. Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.

routes: [
   {
      $id: Now.ID['route1'],
      path: '/home/{id}',
      script: process,
      parameters: [{ $id: Now.ID['param1'],  name: 'n_param' }],
      headers: [{ $id: Now.ID['header1'],  name: 'n_token' }],
      enforceAcl: [acl],
      version: 1,
   },
],

objetos de parâmetros e cabeçalhos

Crie parâmetros de consulta [sys_ws_query_parameter] e cabeçalhos [sys_ws_header] para rotas em uma REST API com script. Os parâmetros de consulta controlam quais valores um usuário solicitante pode passar no URI de solicitação. Os cabeçalhos especificam o que a API aceita e pode responder com.

Use o. parâmetros e. cabeçalhos objetos em rotas objeto.

Tabela 3. Propriedades

Nome	Tipo	Descrição
id	Cadeia de caracteres ou número	Necessário. Um ID exclusivo para o objeto de metadados. Quando você cria a aplicação, este ID é hash em um sys_id exclusivo. Para obter mais informações, consulte ServiceNow Fluent construções de linguagem. Formato: Now.ID['Cadeia de caracteres' ou número]
nome	Cadeia de caracteres	Necessário. O nome do parâmetro ou cabeçalho, que é usado na documentação da API.
obrigatório	Booliano	Sinalizador que indica se o parâmetro ou cabeçalho é necessário. Valores válidos: Verdadeiro: O parâmetro ou cabeçalho é obrigatório. Falso: O parâmetro ou cabeçalho não é necessário. Padrão: falso
ExampleValue	Cadeia de caracteres	Um exemplo de um valor válido para o parâmetro ou cabeçalho, que é usado na documentação da API.
shortDescription	Cadeia de caracteres	Uma breve descrição do parâmetro ou cabeçalho, que é usado na documentação da API.
meta	Objeto	Metadados dos metadados da aplicação. Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas. $meta: {       installMethod: 'String' } Valores válidos para Método de instalação : Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada. Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.

parameters: [{ $id: Now.ID['param1'],  name: 'n_param' }],
headers: [{ $id: Now.ID['header1'],  name: 'n_token' }],

objeto de versões

Crie versões para uma REST API com script [sys_ws_version] para definir endpoints de serviço web.

Use o. versões objeto em RestApi objeto.

Tabela 4. Propriedades

Nome	Tipo	Descrição
id	Cadeia de caracteres ou número	Necessário. Um ID exclusivo para o objeto de metadados. Quando você cria a aplicação, este ID é hash em um sys_id exclusivo. Para obter mais informações, consulte ServiceNow Fluent construções de linguagem. Formato: Now.ID['Cadeia de caracteres' ou número]
versão	Número	Necessário. Uma versão da REST API.
ativo	Booliano	Sinalizador que indica se a versão da REST API pode atender solicitações. Valores válidos: Verdadeiro: A versão da API pode atender solicitações. Falso: A versão da API não pode atender solicitações. Padrão: verdadeiro
obsoleto	Booliano	Sinalizador que indica se a versão da REST API está obsoleta. Os recursos pertencentes a versões obsoletas podem atender a solicitações, mas são identificados como obsoletos na documentação. Valores válidos: Verdadeiro: A versão da API foi identificada como obsoleta. Falso: A versão da API não foi identificada como obsoleta. Padrão: falso
shortDescription	Cadeia de caracteres	Uma breve descrição da versão da REST API, que aparece na documentação da API.
isDefault	Booliano	Sinalizador que indica se a versão da REST API é a versão padrão. Os clientes podem acessar a versão padrão usando o caminho de URI com ou sem versão. Valores válidos: Verdadeiro: A versão da API é a versão padrão. Falso: A versão da API não é a versão padrão. Padrão: falso
meta	Objeto	Metadados dos metadados da aplicação. Com o. Método de instalação , você pode mapear os metadados da aplicação para um diretório de saída que carrega somente em circunstâncias específicas. $meta: {       installMethod: 'String' } Valores válidos para Método de instalação : Demonstração: Gera os metadados da aplicação para o. metadados/unload.demo diretório a ser instalado com a aplicação quando Carregar dados de demonstração a opção está selecionada. Primeira instalação: Gera os metadados da aplicação para o. metadados/descarregamento diretório a ser instalado somente na primeira vez que uma aplicação for instalada em uma instância.

versions: [
 {
   $id: Now.ID['v1'],
   version: 1,
 },
],