スクリプト化 REST API
スクリプト化された REST API 機能を使用すると、アプリケーション開発者はカスタム Web サービス API をビルドできます。
スクリプト化された REST API のサービスエンドポイント、クエリパラメーター、 スキーマ、ヘッダー、および要求と応答を管理するスクリプトを定義できます。
スクリプト化された REST API は、通常は REST アーキテクチャに従いますが、異なる規則を使用するようにカスタマイズすることもできます。スクリプト REST API を定義するには、[ スクリプト化 Web サービス ] → [ スクリプト化 REST API] の下にある [スクリプト化 REST サービス] フォームを使用します。
スクリプト済み REST API URI
スクリプト化された REST API URI の形式は次のとおりです。
https://<instance.service-now.com>/api/<name_space>/<version>/<api_id>/<relative_path>
- <instance.service-now.com>:ユーザーがスクリプト化された REST API にアクセスする ServiceNow インスタンスへのパス。
- <name_space>:グローバルスコープ内の Web サービスの場合、名前空間はプロパティ glide.appcreator.company.codeの値です。スコープ対象のアプリケーション内の Web サービスの場合、名前空間はスコープ名 (x_company_appname など) です。名前空間の詳細については、「 アプリケーションスコープ」を参照してください。
- <version>:オプション。API が v1 などのバージョニングを使用する場合にアクセスしるエンドポイントのバージョン。バージョン番号なしで URI を指定することで、バージョニングされた API のデフォルトバージョンにアクセスできます。
- <api_id>:スクリプト化された REST サービスフォームの API ID フィールドの値。デフォルトでは、この値はサービス名に基づいています。
- <relative_path>:スクリプト化された REST サービスフォームでリソースに定義された相対パス。相対リソースパスを指定すると、GET などの同じ HTTP メソッドを使用して複数のリソースを 1 つの Web サービスで使用できます。たとえば、Web サービスに GET リソースが 1 つしかない場合はパス
/{id}を指定し、Web サービスに要求するユーザーレコードとメッセージレコードのリソースが異なる場合はパス /user/{id}と/message/{id}を指定できます。
スクリプト済み REST API バージョニング
スクリプト化された REST API URI には、 /api/management/v1/table/{tableName} などのバージョン番号を含めることができます。バージョン番号は、URI がアクセスするエンドポイントのバージョンを識別します。URI にバージョン番号を指定することで、既存の統合に影響を与えることなく変更をテストおよび展開できます。
デフォルトの API バージョン
バージョンはデフォルトとしてマークされる場合があります。デフォルトバージョンを指定すると、ユーザーはバージョン番号なしでスクリプト化された REST エンドポイントを使用してそのバージョンにアクセスできます。デフォルトとしてマークされているバージョンがない場合は、最新バージョンがデフォルトとして使用されます。
スクリプト済み REST API リソース
スクリプト化された REST API リソースは、REST エンドポイントと同等です。実行する HTTP メソッド、処理スクリプト、および親 API からの上書き設定を定義します。API ごとに 1 つ以上のリソースを定義できます。
スクリプト済み REST API クエリパラメーター
クエリパラメーターは、要求元ユーザーが要求で渡すことができる値を定義します。スクリプト化された REST API を作成するときに、要求ごとに使用可能なパラメーターと必須のパラメーターを指定できます。クエリパラメーターを複数のリソースに関連付けることもできます。
要求オブジェクトの queryParams フィールドを使用して、スクリプト内の要求パラメーターにアクセスします。
スクリプト済み REST スキーマ
スキーマは、データタイプ、想定されるフィールド、形式など、API 要求と応答に使用できる構造を定義します。スクリプト化された REST API 内で複数のスキーマを定義できます。これを使用して、その API 内のリソースの要求と応答の内容を指定できます。
スキーマは、 OpenAPI バージョン 3.0.1 形式を使用して定義する必要があります。
スクリプト済み REST API ロール
要求と応答のフォーマット
デフォルトでは、API 内のすべてのリソースは、application/json、application/xml、および text/xml の要求と応答の形式をサポートしています。API レベルでデフォルトの形式を上書きできます。個々のリソースがデフォルトを上書きしない限り、新しい形式は API に属するすべてのリソースに適用されます。
スクリプト済み REST API セキュリティ
スクリプト化された REST API は、必要なレベルのセキュリティで構成できます。セキュリティを必要としないパブリック API/エンドポイントから、すべてのリソースに対する厳格なアクセス制御を備えたユーザー認証を必要とする非常に安全な API/エンドポイントまで。
API アクセスポリシー機能を使用して、API の認証方法を制御します。詳細については、「API access policy」を参照してください。
スクリプト化された REST API アクセス制御
アクセス制御リスト (ACL) は、必要なロールや、スクリプト化された REST API またはエンドポイントにアクセスするためにユーザーが満たす必要がある条件などの基準を定義します。要求ユーザーは少なくとも 1 つの ACL を満たす必要があります。選択したすべての ACL を満たす必要はありません。REST API 全体または個々のエンドポイントに対して単一の ACL を定義できます。
Scripted REST API ACL を定義する場合は、[タイプ] の値を [REST_Endpoint] にする必要があります。
ACL の詳細については、「 アクセス制御リストのルール と ACL を要求するようにスクリプト化された REST API リソースを構成する」を参照してください。
スクリプト済み REST API セキュリティマトリクス
スクリプト化された REST API には、複数のセキュリティ構成が考えられます。このテーブルを使用して、ニーズに最適なスクリプト化された REST API セキュリティ構成と、その構成を実装するためのフィールド値を特定します。
| 設定 | スクリプト化 REST API | スクリプト化済み REST リソース | ||
|---|---|---|---|---|
| デフォルト ACL | 承認が必要 | ACL 承認が必要 | ACL | |
| リソースは公開です。認証や ACL は不要です。 | 任意の値 | False | 任意の値 | 任意の値 |
| リソースにはベーシック認証のみが必要です。ACL は必要ありません。 | 任意の値 | true | False | 任意の値 |
| リソースにはベーシック認証のみが必要です。ACL は必須です。 | ACL が選択されていません | true | true | ACL が選択されていません |
| リソースレコードで選択されている ACL は必須です。 | 任意の値 | true | true | 1 つ以上の ACL が選択されました |
| スクリプト化された REST API レコードで選択された ACL が必要です。 | 1 つ以上の ACL が選択されました | true | true | ACL が選択されていません |
スクリプト済み REST API エラーオブジェクト
スクリプト化された REST API には、要求の処理中にエラーが発生した場合に、標準の HTTP エラーメッセージで要求に応答できるエラーオブジェクトが含まれています。スクリプト化された REST API リソースのエラーオブジェクトを使用して、要求元のクライアントにエラーを警告することができます。エラーオブジェクトは、サーバー側のコード内のエラーを検出するのではなく、受信要求に応答するために使用します。
エラー応答形式
応答のコンテンツタイプは、要求の Accept ヘッダーによって異なります。Accept ヘッダーで image/jpeg などのサポートされていない形式が指定されている場合、エラー応答は JSON を使用します。
{
"error": {
"message": "My error message",
"detail": "My details"
},
"status": "failure"
}自動テストフレームワーク (ATF) のサポート
自動テストフレームワーク (ATF) は、受信 REST テストステップをサポートしています。作成したカスタム受信 REST API の自動テストを作成できます。カスタム REST API のテストを作成すると、アップグレードテストが簡素化され、REST API への変更に下位互換性があることを検証できます。「REST テストステップ構成の管理」および「ATF REST テストステップ構成」を参照してください。
開発者トレーニング
ServiceNow® 開発者サイトには、スクリプト済み REST API のトレーニングがあります。