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

  • リリースバージョン: Zurich
  • 更新日 2025年07月31日
  • 所要時間：15分

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

    スクリプト化された REST Services の詳細については、「 Scripted REST APIs」を参照してください。

    RestApi オブジェクト

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

    表 : 1. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。API ドキュメントで使用される API の名前。
    serviceId 文字列 必須。URI パスでこの API を区別するために使用される API 識別子。API 名前空間内で一意である必要があります。
    active ブーリアン API が要求を処理できるかどうかを示すフラグ。
    有効な値：
    • true：API は要求を処理できます。
    • false：API は要求を処理できません。

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

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

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

    デフォルト：スクリプト済み 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 のさまざまなバージョンとそのステータス (アクティブ、デフォルトバージョン、廃止など) を管理できます。
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    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,
        },
    ],
})
    参照される 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,
    adminOverrides: false,
    operations: ['execute'],
})

    routes オブジェクト

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

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

    表 : 2. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 API ドキュメントで使用される API リソースの名前。

    デフォルト：path プロパティの値
    script スクリプト 必須。カスタムスクリプトは、操作が要求を解析して応答する方法を定義します。 このプロパティは、JavaScript モジュールからの関数、スクリプトを含むアプリケーション内の別のファイルへの参照、またはインライン JavaScript をサポートします。
    Format (形式)：
    • 関数には、JavaScript モジュールからエクスポートされた関数、関数式、またはデフォルト関数の名前を使用し、 .now.ts ファイルにインポートします。JavaScript モジュールの詳細については、「 JavaScript モジュールとサードパーティライブラリ」を参照してください。
    • 別のファイルのテキストコンテンツを使用するには、 Now.include('path/to/file') の形式を使用してアプリケーションでファイルを参照します。詳細については、「ServiceNow Fluent 言語構成」を参照してください。
    • インラインスクリプトを指定するには、複数行のコードに文字列リテラルまたはテンプレートリテラルを使用します ( 「スクリプト」または「スクリプト」)。
    parameters アレイ ルートのクエリパラメーター [sys_ws_query_parameter] のリスト。詳細については、「パラメーターとヘッダーのオブジェクト」を参照してください。
    ヘッダー アレイ ルートのヘッダー [sys_ws_header] のリスト。詳細については、「パラメーターとヘッダーのオブジェクト」を参照してください。
    アクティブ ブーリアン リソースが使用されるかどうかを示すフラグ。
    有効な値：
    • true：リソースが使用されます。
    • false：リソースは使用されません。

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

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

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

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

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

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

    デフォルト：RestApi オブジェクトの produces プロパティの値
    requestExample 文字列 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 がアクセスするエンドポイントのバージョンを識別します。バージョン番号を指定することで、既存の統合に影響を与えることなく変更をテストおよび展開できます。
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    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,
   },
],

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

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

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

    表 : 3. プロパティ
    名前 タイプ 説明
    $id 文字列または数値 必須。メタデータオブジェクトの一意の ID。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    name 文字列 必須。API ドキュメントで使用されるパラメーターまたはヘッダーの名前。
    required ブーリアン パラメーターまたはヘッダーが必須かどうかを示すフラグ。
    有効な値：
    • true：パラメーターまたはヘッダーは必須です。
    • false：パラメーターまたはヘッダーは必要ありません。

    デフォルト値：false
    exampleValue 文字列 API ドキュメントで使用される、パラメーターまたはヘッダーの有効な値の例。
    shortDescription 文字列 API ドキュメントで使用されるパラメーターまたはヘッダーの簡単な説明。
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    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。アプリケーションをビルドすると、この ID は一意のsys_idにハッシュされます。詳細については、「ServiceNow Fluent 言語構成」を参照してください。

    形式: Now.ID['string' or number]
    version 番号 必須。REST API のバージョン。
    active ブーリアン REST API のバージョンが要求を処理できるかどうかを示すフラグ。
    有効な値：
    • true：API のバージョンは要求を処理できます。
    • false：API のバージョンは要求を処理できません。

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

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

    デフォルト値：false
    $meta オブジェクト アプリケーションメタデータのメタデータ。
    installMethod プロパティを使用すると、特定の状況でのみロードされる出力ディレクトリにアプリケーションメタデータをマップできます。
    $meta: {
      installMethod: 'String'
}
    installMethod の有効な値:
    • demo:[デモデータのロード] オプションが選択されている場合、アプリケーションメタデータを metadata/unload.demo ディレクトリに出力して、アプリケーションとともにインストールします。
    • 初回インストール:アプリケーションがインスタンスに初めてインストールされたときにのみインストールされるように 、アプリケーションメタデータをメタデータ/アンロード ディレクトリに出力します。
    		 
    versions: [
 {
   $id: Now.ID['v1'],
   version: 1,
 },
],