スクリプト済み REST API - ServiceNow Fluent

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：11分

    • スクリプト済み REST API には、スクリプト済み REST サービス [sys_ws_definition] のエンドポイント、クエリパラメーター、およびヘッダーを定義するオブジェクトが含まれます。

    RestApi オブジェクト

    スクリプト済み REST API [sys_ws_definition] を作成して、Web サービスエンドポイントを定義します。

    表 : 1. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。次の形式で提供されるメタデータオブジェクトの一意の ID。ここで、<value> は文字列または数値です。
    $id: Now.ID[<value>]

    アプリケーションをビルドすると、この ID は一意の sys_ID にハッシュされます。
    name 文字列 必須。API ドキュメントで使用される API の名前。
    service_id 文字列 必須。URI パスでこの API を区別するために使用される API 識別子。API 名前空間内で一意である必要があります。
    active ブーリアン API が要求を処理できるかどうかを示すフラグ。
    有効な値：
    • true：API は要求を処理できます。
    • false：API は要求を処理できません。

    デフォルト：true
    short_description 文字列 API ドキュメントで使用される API の簡単な説明。
    consumes 文字列 API のリソースが消費できるメディアタイプのリスト。

    デフォルト：application/json、application/xml、text/xml
    doc_link 文字列 API に関する静的ドキュメントにリンクする URL。
    enforce_acl アレイ リソース [sys_security_acl] へのアクセス時に適用する ACL オブジェクトの変数識別子または ACL の sys_ids のリスト。詳細については、「アクセス制御リスト API - ServiceNow Fluent」を参照してください。

    ACL を適用しない場合は、このプロパティを空のアレイ ([]) に設定します。

    enforce_acl: ['sys_id', acl_variable_identifier]

    デフォルト：スクリプト済み REST 外部デフォルト
    produces 文字列 API のリソースが生成できるメディアタイプのリスト。

    デフォルト：application/json、application/xml、text/xml
    routes アレイ API のリソース [sys_ws_operation]。詳細については、「routes オブジェクト」を参照してください。
    policy 文字列 アプリケーションファイルをダウンロードまたはインストールするときに保護する方法に関するポリシー。
    有効な値：
    • read：ファイルは表示のみ可能です。
    • protected：パスワード権限を持つユーザーがファイルを編集できます。
    versions アレイ API のバージョン [sys_ws_version] のリスト。詳細については、「versions オブジェクト」を参照してください。

    バージョンを指定すると、API のさまざまなバージョンとそのステータス (アクティブ、デフォルトバージョン、廃止など) を管理できます。

    		 
    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,
        },
    ],
})
    参照される ACL は、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'],
})

    routes オブジェクト

    スクリプト済み REST リソース [sys_ws_operation] を作成して、HTTP メソッドと処理スクリプトを定義し、親サービスからの設定を上書きします。

    RestApi オブジェクト内の routes オブジェクトを使用します。

    表 : 2. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。次の形式で提供されるメタデータオブジェクトの一意の ID。ここで、<value> は文字列または数値です。
    $id: Now.ID[<value>]

    アプリケーションをビルドすると、この ID は一意の sys_ID にハッシュされます。
    name 文字列 API ドキュメントで使用される API リソースの名前。

    デフォルト：path プロパティの値
    script スクリプト 必須。script タグが前に付いた関数またはインラインスクリプト。カスタムスクリプトは、操作が要求を解析して応答する方法を定義します。

    関数には、JavaScript モジュールからエクスポートされて .now.ts ファイルにインポートされた関数、関数式、またはデフォルト関数の名前を使用します。JavaScript モジュールの詳細については、「JavaScript モジュールとサードパーティライブラリ」を参照してください。

    インラインスクリプトは、script タグを次の形式で使用します。
    script: script`gs.info('info')`,
    active ブーリアン リソースが使用されるかどうかを示すフラグ。
    有効な値：
    • true：リソースが使用されます。
    • false：リソースは使用されません。

    デフォルト：true
    path 文字列 ベース API パスに対するリソースの相対パス。相対 URI には、/abc/{id} などのパスパラメーターを含めることができます。

    デフォルト：/
    short_description 文字列 API ドキュメントで使用される、リソースの簡単な説明。
    consumes 文字列 リソースが消費できるメディアタイプのリスト。

    このプロパティは、PUT、PATCH、または POST メソッドで上書きできます。

    デフォルト：RestApi オブジェクトの consumes プロパティの値
    enforce_acl アレイ リソース [sys_security_acl] へのアクセス時に適用する ACL オブジェクトの変数識別子または ACL の sys_ids のリスト。詳細については、「アクセス制御リスト API - ServiceNow Fluent」を参照してください。

    ACL を適用しない場合は、このプロパティを空のアレイ ([]) に設定します。

    enforce_acl: ['sys_id', acl_variable_identifier]

    デフォルト：スクリプト済み REST 外部デフォルト
    produces 文字列 リソースが生成できるメディアタイプのリスト。

    デフォルト：RestApi オブジェクトの produces プロパティの値
    request_example 文字列 API ドキュメントで使用される、リソースの有効なサンプル要求の本文ペイロード。
    method 文字列 リソースが実装する HTTP メソッド。

    有効な値：GET、POST、PUT、PATCH、DELETE

    デフォルト：GET
    authorization ブーリアン リソースにアクセスするためにユーザーが認証される必要があるかどうかを示すフラグ。
    有効な値：
    • true：ユーザーはリソースにアクセスするために認証される必要があります。
    • false：リソースへのアクセスに認証は必要ありません。

    デフォルト：true
    認証 ブーリアン リソースへのアクセス時に ACL を適用するかどうかを示すフラグ。
    有効な値：
    • true：リソースへのアクセス時に ACL が適用されます。
    • false：リソースへのアクセス時に ACL は適用されません。

    デフォルト：true
    internalRole ブーリアン ルートに snc_internal ロールが必要かどうかを示すフラグ。

    このプロパティは、明示的なロールプラグイン (com.glide.explicit_roles) が有効な場合のみサポートされます。

    有効な値：
    • true：ルートには snc_internal ロールが必要です。
    • false：ルートに snc_internal ロールは必要ありません。

    デフォルト：true
    policy 文字列 アプリケーションファイルをダウンロードまたはインストールするときに保護する方法に関するポリシー。
    有効な値：
    • read：ファイルは表示のみ可能です。
    • protected：パスワード権限を持つユーザーがファイルを編集できます。
    version 番号 API のバージョン。

    versions プロパティが RestApi オブジェクトで使用されている場合、このプロパティは必須です。

    このプロパティで指定されたバージョンは、/api/management/v1/table/{tableName} などのバージョンで URI を自動的に生成するために使用されます。バージョン番号は、URI がアクセスするエンドポイントのバージョンを識別します。バージョン番号を指定することで、既存の統合に影響を与えることなく変更をテストおよび展開できます。

    		 
    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,
   },
],

    パラメーターとヘッダーのオブジェクト

    スクリプト済み REST API でルートのクエリパラメーター [sys_ws_query_parameter] とヘッダー [sys_ws_header] を作成します。クエリパラメーターは、要求ユーザーが要求 URI で渡すことができる値を制御します。ヘッダーは、API が受け入れ、応答できる内容を指定します。

    routes オブジェクト内の parameters オブジェクトと headers オブジェクトを使用します。

    表 : 3. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。次の形式で提供されるメタデータオブジェクトの一意の ID。ここで、<value> は文字列または数値です。
    $id: Now.ID[<value>]

    アプリケーションをビルドすると、この ID は一意の sys_ID にハッシュされます。
    name 文字列 必須。API ドキュメントで使用されるパラメーターまたはヘッダーの名前。
    required ブーリアン パラメーターまたはヘッダーが必須かどうかを示すフラグ。
    有効な値：
    • true：パラメーターまたはヘッダーは必須です。
    • false：パラメーターまたはヘッダーは必要ありません。

    デフォルト値：false
    example_value 文字列 API ドキュメントで使用される、パラメーターまたはヘッダーの有効な値の例。
    short_description 文字列 API ドキュメントで使用されるパラメーターまたはヘッダーの簡単な説明。 
    parameters: [{ $id: Now.ID['param1'],  name: 'n_param' }],
headers: [{ $id: Now.ID['header1'],  name: 'n_token' }],

    versions オブジェクト

    スクリプト済み REST API [sys_ws_version] のバージョンを作成して、Web サービスエンドポイントを定義します。

    RestApi オブジェクト内の versions オブジェクトを使用します。

    表 : 4. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。次の形式で提供されるメタデータオブジェクトの一意の ID。ここで、<value> は文字列または数値です。
    $id: Now.ID[<value>]

    アプリケーションをビルドすると、この ID は一意の sys_ID にハッシュされます。
    version 番号 必須。REST API のバージョン。
    active ブーリアン REST API のバージョンが要求を処理できるかどうかを示すフラグ。
    有効な値：
    • true：API のバージョンは要求を処理できます。
    • false：API のバージョンは要求を処理できません。

    デフォルト：true
    deprecated ブーリアン REST API のバージョンが廃止されているかどうかを示すフラグ。廃止されたバージョンに属するリソースは要求を処理できますが、ドキュメントでは「廃止」として識別されます。
    有効な値：
    • true：API のバージョンは廃止として識別されます。
    • false：API のバージョンは廃止として識別されません。

    デフォルト値：false
    short_description 文字列 API ドキュメントに表示される REST API のバージョンの簡単な説明。
    is_default ブーリアン REST API のバージョンがデフォルトバージョンかどうかを示すフラグ。クライアントは、バージョンニングされている URI パスまたはバージョニングされていない URI パスを使用して、デフォルトバージョンにアクセスできます。
    有効な値：
    • true：API のバージョンがデフォルトバージョンです。
    • false：API のバージョンはデフォルトバージョンではありません。

    デフォルト値：false

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