---
sourceDocument: Xanadu API リファレンス
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/xanadu/api-reference

 Release :

    - xanadu

ft:locale :

    - ja-JP

ft:publication_title :

    - Xanadu API リファレンス

ft:clusterId :

    - crapiref

bundleId :

    - crapiref

workflow :

    - Creator


---

# Scripted REST APIs

# Scripted REST APIs {#ariaid-title1}

* リリースバージョン: Xanadu
* 
* 更新日 2024年08月01日
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：8分

Scripted REST API 機能を使用すると、アプリケーション開発者はカスタム Web サービス API を構築できます。

サービスエンドポイント、クエリパラメーター、Scripted REST API のヘッダー、および要求と応答を管理するスクリプトを定義できます。

Scripted REST APIs は通常 REST アーキテクチャに従いますが、別の規則を使用するようにカスタマイズできます。Scripted REST APIs を定義するには、\[スクリプト利用 Web サービス\] → \[Scripted REST APIs\] にある \[スクリプト化済み REST サービス\] フォームを使用します。  
図 : 1. スクリプト化済み REST サービスフォーム  
次のビデオでは、スクリプト化された REST API に関する追加情報を提供しています。

* [スクリプト済み REST API -- 設計](https://www.youtube.com/watch?v=Tw70sHgDc-w)
* [スクリプト済み REST API -- 実装](https://www.youtube.com/watch?v=LFHV-Qk1-Yk)
{#c_CustomWebServices__ul_bjx_c3b_vzb}

## Scripted REST API URI {#c_CustomWebServices__section_upf_pn4_zhb}

Scripted REST API URI の形式は次のとおりです。

https://\<instance.service-now.com\>/api/\<name_space\>/\<version\>/\<api_id\>/\<relative_path\>  
この URI の場合：

* \<instance.service-now.com\>：ユーザーが Scripted REST API にアクセスする ServiceNow インスタンスへのパス。
* \<name_space\>：グローバルスコープ内の Web サービスの場合、名前空間はプロパティ glide.appcreator.company.code の値です。スコープ対象のアプリケーションの Web サービスの場合、名前空間は x_company_appname などのスコープ名です。名前空間の詳細については、「 [アプリケーションスコープ](https://www.servicenow.com/docs/access?context=c_ApplicationScope&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US)」を参照してください。
* \<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}` を指定します。
{#c_CustomWebServices__ul_osv_kgc_lr}

## Scripted REST API バージョニング {#c_CustomWebServices__section_pnw_c44_zhb}

Scripted REST API URI には、/api/management/v1/table/{tableName} などのバージョン番号を含めることができます。バージョン番号は URI がアクセスするエンドポイントのバージョンを識別します。URI にバージョン番号を指定することで、既存の統合に影響を与えることなく変更をテストおよび展開できます。

## デフォルトの API バージョン {#c_CustomWebServices__section_jgj_b44_zhb}

バージョンがデフォルトとしてマークされている場合があります。デフォルトバージョンを指定すると、ユーザーはバージョン番号なしでスクリプト化された REST エンドポイントを使用してそのバージョンにアクセスできます。デフォルトとしてマークされているバージョンがない場合は、最新バージョンがデフォルトとして使用されます。

## Scripted REST API リソース {#c_CustomWebServices__section_fhh_3nw_23b}

Scripted REST API リソースは REST エンドポイントに相当します。実行する HTTP メソッド、処理スクリプト、および親 API からの任意の上書き設定を定義します。API ごとに 1 つ以上のリソースを定義できます。

## Scripted REST API クエリパラメーター {#c_CustomWebServices__section_tfl_444_zhb}

クエリパラメーターは要求ユーザーが要求で渡すことができる値を定義します。Scripted REST API を作成するときに、各要求で使用可能なパラメーターと必須パラメーターを指定できます。クエリパラメーターを複数のリソースに関連付けることもできます。

要求オブジェクトの queryParams フィールドを使用して、スクリプトの要求パラメーターにアクセスします。

## Scripted REST API ロール {#c_CustomWebServices__section_y5m_xx4_zhb}

Scripted REST APIs を使用するには、Web サービス管理者 \[web_service_admin\] ロールが必要です。このロールを持つユーザーは、Scripted REST APIs および Web サービスリソースを読み込み、作成、変更、削除できます。  
注:  
これらのロールは Scripted REST API エンドポイントへのアクセスには必要ありません。

## 要求および応答の形式 {#c_CustomWebServices__section_p3s_fkw_23b}

デフォルトでは、API 内のすべてのリソースは、application/json、application/xml、および text/xml の要求および応答形式をサポートしています。API レベルでデフォルトの形式を上書きできます。個々のリソースでデフォルトを上書きしない限り、新しい形式は API に属するすべてのリソースに適用されます。

## Scripted REST API セキュリティ {#c_CustomWebServices__section_txq_hx4_zhb}

必要なセキュリティレベルで Scripted REST APIs を設定できます。セキュリティを必要としないパブリック API/エンドポイントから、すべてのリソースに対するアクセス制御が厳格なユーザー認証を必要とする安全性の高い API/エンドポイントまで設定できます。

API アクセスポリシー機能を使用して、API の認証方法を制御します。詳細については、「[API access policy](https://www.servicenow.com/docs/access?context=api-access-policy&version=xanadu&pubname=xanadu-platform-security&ft:locale=en-US)」を参照してください。

## Scripted REST API アクセス制御 {#c_CustomWebServices__section_rbc_zz4_zhb}

アクセス制御リスト (ACL) は、必要なロールや、ユーザーが Scripted REST API またはエンドポイントにアクセスするために満たす必要がある条件などの基準を定義します。要求ユーザーは少なくとも 1 つの ACL を満たす必要があります。選択したすべての ACL を満たす必要はありません。REST API 全体または個々のエンドポイントに対して単一の ACL を定義できます。  
注:  
デフォルトでは、Scripted REST APIs には snc_external ロールを持つユーザーが API に要求を行うことを禁止する ACL が含まれています。

Scripted REST API ACL を定義する場合は、\[タイプ\] の値を \[REST_Endpoint\] にする必要があります。

ACL の詳細については、「 [アクセス制御リストのルール](https://www.servicenow.com/docs/access?context=access-control-rules&version=xanadu&pubname=xanadu-platform-security&ft:locale=en-US) と [Scripted REST API リソースを構成して ACL を要求する](https://servicenow-prod.fluidtopics.net/li1~QcaNa~VxVkbygUmg3A "デフォルトでは、API リソース/エンドポイントは親 API からセキュリティ設定を継承します。特定のリソース/エンドポイントのカスタム ACL を定義して、継承された設定を上書きします。")」を参照してください。

## Scripted REST API セキュリティマトリクス {#c_CustomWebServices__section_xww_cgp_zhb}

Scripted REST APIs には複数のセキュリティ設定があります。このテーブルを使用して、ニーズに最適な Scripted REST API セキュリティ構成と、その構成を実装するフィールド値を特定します。
{#c_CustomWebServices__table_r2p_vbt_tr__entry__3}{#c_CustomWebServices__table_r2p_vbt_tr__entry__8}

| 設定 | 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 が選択されていません |
[表 : 1. Scripted REST API セキュリティ]

{#c_CustomWebServices__table_r2p_vbt_tr}

## Scripted REST API エラーオブジェクト {#c_CustomWebServices__section_xkj_5gp_zhb}

Scripted REST APIs にはエラーオブジェクトが含まれており、これを使用して要求の処理中にエラーが発生したときに標準の HTTP エラーメッセージで要求に応答できます。Scripted REST API リソースでエラーオブジェクトを使用して、要求元のクライアントにエラーを警告できます。エラーオブジェクトは、サーバー側のコード内のエラーを検出するためではなく、受信要求に応答するために使用します。

## エラー応答形式 {#c_CustomWebServices__section_f2v_1hp_zhb}

応答のコンテンツタイプは要求の Accept ヘッダーによって異なります。Accept ヘッダーでサポートされていない形式 (image/jpeg など) が指定されている場合、エラー応答は JSON を使用します。  
エラー応答は次の形式に従います。

    {
      "error": {
        "message": "My error message",
        "detail": "My details"  
      },  
      "status": "failure"
    }

数値のステータスコード (404 など) は、応答本文ではなく、応答の Status code ヘッダーに含まれます。

## Automated Test Framework のサポート

[Automated Test Framework](https://www.servicenow.com/docs/access?context=automated-test-framework&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US) (ATF) は、受信 REST テストステップをサポートしています。作成したカスタム受信 REST API の自動テストを作成できます。カスタム REST API のテストを作成すると、アップグレードのテストが簡素化され、REST API の変更に下位互換性があることを検証することが可能になります。「[REST テストステップ構成の管理](https://www.servicenow.com/docs/access?context=atf-administer-rest&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US)」および「[ATF REST テストステップ構成](https://www.servicenow.com/docs/access?context=rest-test-steps&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US)」を参照してください。

## 開発者トレーニング {#c_CustomWebServices__section_dk2_2cc_2hb}

ServiceNow® 開発者サイト には、[Scripted REST APIs](https://developer.servicenow.com/app.do#!/training/article/app_store_learnv2_rest_paris_scripted_rest_apis/app_store_learnv2_rest_paris_scripted_rest_api_objectives?v=paris) のトレーニングがあります。
* **[Scripted REST API の作成](https://servicenow-prod.fluidtopics.net/6~e5AuFP2hLih9uEB3iV9w)**   
  Scripted REST API を作成して、Web サービスエンドポイントを定義します。
* **[Scripted REST APIs の推奨プラクティス](https://servicenow-prod.fluidtopics.net/ALyzw4QGx1JFbTYsyc2juQ)**   
  Scripted REST APIs を設計および実装するときは、次のガイドラインに従ってください。
* **[Scripted REST API の例](https://servicenow-prod.fluidtopics.net/OA3plFhQOvfOMCxlkpdFWA)**   
  Scripted REST APIs の作成と使用方法を示す複数の例が用意されています。