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