Scripted REST API - ServiceNow Fluent

A Scripted REST API inclui objetos que definem os endpoints, parâmetros de consulta e cabeçalhos para um serviço REST com script [sys_ws_definition].

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	Obrigatório. Um ID exclusivo para o objeto de metadados fornecido no seguinte formato, em que<value> é uma cadeia de caracteres ou um número. $id: Now.ID[<value>] Quando você cria a aplicação, esse ID é convertido em um sys_ID exclusivo.
nome	Cadeia de caracteres	Obrigatório. O nome da API, que é usado na documentação da API.
service_id	Cadeia de caracteres	Obrigatório. O identificador de API usado para distinguir esta API em caminhos de URI. Deve ser exclusivo no namespace da API.
ativo	Booliano	Sinalizador que indica se a API pode atender a solicitações. Valores válidos: verdadeiro: a API pode atender a solicitações. falso: a API não pode atender a solicitações. Padrão: verdadeiro
short_description	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
doc_link	Cadeia de caracteres	Uma URL que vincula à documentação estática sobre a API.
impor_acl	Matriz	Uma lista de identificadores de variáveis de objetos de ACL ou sys_ids de ACLs a serem impostos 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 ([]). enforce_acl: ['sys_id', acl_variable_identifier] Padrão: padrão externo de REST de script
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] para a API. Para obter mais informações, consulte objeto de rotas.
política	Cadeia de caracteres	A política de como os arquivos de aplicações são protegidos quando baixados ou instalados. Valores válidos: leitura: os arquivos são somente visíveis. protected: 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. Especificar versões permite gerenciar diferentes versões de uma API e seus status, por exemplo, se estão ativas, a versão padrão ou obsoletas.

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

RestApi({
    $id: Now.ID['rest1'],
    name: 'customAPI',
    service_id: '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' }],
            enforce_acl: [acl],
            version: 1,
        },
    ],
    enforce_acl: [acl],
    versions: [
        {
            $id: Now.ID['v1'],
            version: 1,
        },
    ],
})

A ACL referenciada é definida usando o objeto ACL :

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

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

objeto de rotas

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

Use o objeto de rotas no objeto RestApi.

Tabela 2. Propriedades

Nome	Tipo	Descrição
$ID	Cadeia de caracteres ou número	Obrigatório. Um ID exclusivo para o objeto de metadados fornecido no seguinte formato, em que<value> é uma cadeia de caracteres ou um número. $id: Now.ID[<value>] Quando você cria a aplicação, esse ID é convertido em um sys_ID exclusivo.
nome	Cadeia de caracteres	O nome do recurso de API, que é usado na documentação da API. Padrão: o valor da propriedade de caminho
script	Script	Obrigatório. Uma função ou script em linha precedido por um marcador de script. O script personalizado define como a operação analisa e responde às solicitações. 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 importada para o arquivo .now.ts. Para obter informações sobre módulos JavaScript, consulte Módulos JavaScript e bibliotecas de terceiros. Os scripts em linha usam o marcador de script no seguinte formato: script: script`gs.info('info')`,
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: /
short_description	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 da propriedade de consumos no objeto RestApi
impor_acl	Matriz	Uma lista de identificadores de variáveis de objetos de ACL ou sys_ids de ACLs a serem impostos 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 ([]). enforce_acl: ['sys_id', acl_variable_identifier] Padrão: padrão externo de REST de script
produz	Cadeia de caracteres	Uma lista de tipos de mídia que o recurso pode produzir. Padrão: o valor da propriedade de produção no objeto RestApi
solicitação_exemplo	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 que o recurso implementa. Valores válidos: GET, POST, PUT, PATCH, DELETE Padrão: GET
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
funçãointerna	Booliano	Sinalizador que indica se a rota requer a função snc_internal. Esta propriedade será compatível somente se o plug-in Explicit Roles (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 de aplicações são protegidos quando baixados ou instalados. Valores válidos: leitura: os arquivos são somente visíveis. protected: 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 a propriedade de versões for usada no objeto RestApi. A versão especificada com esta propriedade é usada para gerar automaticamente um URI com uma versão, como /api/management/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, você pode testar e implantar mudanças sem afetar as integrações existentes.

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' }],
      enforce_acl: [acl],
      version: 1,
   },
],

parâmetros e objetos de 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 com o que pode responder.

Use os objetos de parâmetros e cabeçalhos no objeto de rotas.

Tabela 3. Propriedades

Nome	Tipo	Descrição
$ID	Cadeia de caracteres ou número	Obrigatório. Um ID exclusivo para o objeto de metadados fornecido no seguinte formato, em que<value> é uma cadeia de caracteres ou um número. $id: Now.ID[<value>] Quando você cria a aplicação, esse ID é convertido em um sys_ID exclusivo.
nome	Cadeia de caracteres	Obrigató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
exemplo_valor	Cadeia de caracteres	Um exemplo de um valor válido para o parâmetro ou cabeçalho, que é usado na documentação da API.
short_description	Cadeia de caracteres	Uma breve descrição do parâmetro ou cabeçalho, que é usada na documentação da API.

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 objeto de versões no objeto RestApi.

Tabela 4. Propriedades

Nome	Tipo	Descrição
$ID	Cadeia de caracteres ou número	Obrigatório. Um ID exclusivo para o objeto de metadados fornecido no seguinte formato, em que<value> é uma cadeia de caracteres ou um número. $id: Now.ID[<value>] Quando você cria a aplicação, esse ID é convertido em um sys_ID exclusivo.
versão	Número	Obrigatório. Uma versão da REST API.
ativo	Booliano	Sinalizador que indica se a versão da REST API pode atender a solicitações. Valores válidos: verdadeiro: a versão da API pode atender a solicitações. falso: a versão da API não pode atender a 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 descontinuadas podem atender às solicitações, mas são identificados como descontinuados na documentação. Valores válidos: verdadeiro: a versão da API foi identificada como obsoleta. falso: a versão da API não está identificada como obsoleta. Padrão: falso
short_description	Cadeia de caracteres	Uma breve descrição da versão da REST API, que aparece na documentação da API.
is_default	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 do URI com ou sem controle de 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

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