エンタイトルメント API の検証

Xanadu API リファレンス

Release

xanadu

ft:locale

ja-JP

ft:publication_title

Xanadu API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

エンタイトルメント API の検証

リリースバージョン: Xanadu

更新日 2024年08月01日

所要時間：29分

エンタイトルメントの検証 API は、有効なエンタイトルメントのリスト、エンタイトルメントの特性に関する詳細、およびエンタイトルメントの最新の使用状況情報を取得できるエンドポイントを提供します。

この API にアクセスするには、エンタイトルメント検証 (sn_ent_verify) プラグインを有効にする必要があります。

この API は、 sn_ent_verify 名前空間内で提供されます。

呼び出し元ユーザーには、sn_pss_core.pss_integrator ロールが必要です。

この API の REST エンドポイントは、次のテーブルからデータをクエリします。

アカウント (customer_account)
コンシューマー (csm_consumer)
エンタイトルメント [service_entitlement]
エンタイトルメント特性 [sn_pss_core_entitlement_characteristic]
エンタイトルメントの使用状況 [sn_pss_core_entitlement_usage]
世帯 [csm_household]
インストールベース [sn_install_base_item]
製品オファリング [sn_prd_pm_product_offering]
製品モデル [cmdb_model]
サービス契約 [sn_pss_core_service_contract]
サービス契約品目 [sn_pss_core_service_contract_line]
販売済み製品 [sn_install_base_sold_product]

エンタイトルメントの検証:/sn_ent_verify/verifyentitlements

指定されたフィルターに基づいて、有効なエンタイトルメントレコードを返します。

エンタイトルメントは、以下に基づいてフィルタリングできます。

アカウント
コンシューマー
契約
世帯
インストールベース
製品モデル
製品オファリング
サービス契約品目
販売済みエンタイトルメント
販売済み製品
状況

少なくとも、エンタイトルメントをフィルターするアカウントまたはコンシューマーのいずれかを指定する必要があります。

複数のフィルターパラメーターが渡された場合、エンドポイントは AND 演算子をパラメーターに適用します。たとえば、「 account = boxeo」 や 「state = draft」などのフィルターパラメーターを渡すと、エンドポイントは Account = boxeo AND state = draft のすべてのエンタイトルメントを返します。

システムのページネーションパラメーター sysparm_offset と sysparm_limit を渡すことで、返される結果のページネーションを実装できます。デフォルトでは、 sysparm_offset は 0 に設定され、 sysparm_limit は 10 に設定されます。したがって、フィルターを適用した後に、100 件のエンタイトルメントが基準を満たした場合、応答には最初の 10 件のエンタイトルメントが含まれます。これらの値は、エンドポイント呼び出しで渡すことで変更できます。

URL 形式

バージョン管理された URL: /api/sn_ent_verify/v1/verifyentitlements

デフォルト URL: /api/sn_ent_verify/verifyentitlements

サポートされている要求パラメーター

表 : 1. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。たとえば、`v1` や `v2`。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列
sysparm_limit	オプション。返されるレコードの最大数。このレコード数を超える要求の場合は、sysparm_offset パラメーターを使用してレコード取得をページネーションします。応答では、ブール値のパラメーター hasMore が返されます。フィルター基準を満たす、返されるレコードがまだあるかどうかを示します。データタイプ：数値デフォルト：10 最大：100
sysparm_offset	オプション。レコード取得を開始するレコードのインデックス。この値を使用して、レコード取得をページネーションします。この機能により、レコード数に関係なく、管理しやすい小さなチャンクに分割してすべてのレコードを取得できます。たとえば、このエンドポイントを初めて呼び出すときに、sysparm_offset は「0」に設定されます。単に利用可能なすべてのレコードをページングするには、すべてのレコードの終わりに達するまで「`sysparm_offset=sysparm_offset+sysparm_limit`」を使用します。 sysparm_offset パラメーターには負数を指定しないでください。データタイプ：数値デフォルト：0

表 : 2. クエリパラメーター
名前	説明
アカウント	account または consumer パラメーターのいずれかを渡す必要があります。これらは相互に排他的です。エンタイトルメントレコードを返すアカウントレコードのSys_id。アカウント [customer_account] テーブルにあります。データタイプ：文字列デフォルト：なし
consumer	account または consumer パラメーターのいずれかを渡す必要があります。これらは相互に排他的です。エンタイトルメントレコードを返すコンシューマーレコードのSys_id。コンシューマー [csm_consumer] テーブルにあります。データタイプ：文字列デフォルト：なし
契約	エンタイトルメントレコードを返す契約レコードのSys_id。契約 [sn_pss_core_service_contract] テーブルにあります。データタイプ：文字列デフォルト：なし
display_value	関連付けられたフィールド値、表示値、またはその両方を返すかどうかを示すフラグ。有効な値： true:応答にはフィールドの表示値のみが含まれます。例: `"state": "Draft"`。 false:応答にはフィールドの値のみが含まれます。例: `"state": "draft"`。 all:応答には、フィールドのすべての情報が含まれます。例： `"state": { "name": "state", "label": "State", "value": "draft", "display_value": "Draft", "type": "string" },` データタイプ：文字列デフォルト値：false
世帯	エンタイトルメントレコードを返す世帯レコードのSys_id。世帯 [csm_household] テーブルにあります。データタイプ：文字列デフォルト：なし
install_base	エンタイトルメントレコードを返すインストールベースレコードのSys_id。インストールベース [sn_install_base_item] テーブルにあります。エンドポイントは、インストールベースレコードのsys_idを使用して、対象の販売済み製品 [sn_install_base_m2m_contract_sold_product] テーブルを検索し、関連するインストールベースの対象となるすべてのエンタイトルメントを返します。データタイプ：文字列デフォルト：なし
product	エンタイトルメントレコードを返す製品レコードのSys_id。製品モデル [cmdb_model] テーブルにあります。データタイプ：文字列デフォルト：なし
product_offering	エンタイトルメントレコードを返す製品オファリングレコードのSys_id。製品オファリング [sn_prd_pm_product_offering] テーブルにあります。データタイプ：文字列デフォルト：なし
service_contract_line	エンタイトルメントレコードを返すサービス契約品目レコードのSys_id。サービス契約品目 [sn_pss_core_service_contract_line] テーブルにあります。データタイプ：文字列デフォルト：なし
sold_entitlement	エンタイトルメントレコードを返す販売済みエンタイトルメントレコードのSys_id。販売済み製品テーブル [sn_install_base_sold_product] テーブルにあります。データタイプ：文字列デフォルト：なし
sold_product	エンタイトルメントレコードを返す販売済み製品レコードのSys_id。販売済み製品テーブル [sn_install_base_sold_product] テーブルにあります。エンドポイントは、販売済み製品レコードのsys_idを使用して、対象の販売済み製品 [sn_install_base_m2m_contract_sold_product] テーブルを検索し、関連する販売済み製品の対象となるすべてのエンタイトルメントを返します。データタイプ：文字列デフォルト：なし
state	返却するエンタイトルメントのステータス。有効な値： active キャンセルドラフト期限切れ中断データタイプ：文字列デフォルト：すべて

表 : 3. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 4. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。デフォルト： application/json

表 : 5. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 6. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
403	禁止されました。ユーザーには、指定されたレコードへのアクセス権がありません。
404	見つかりません。要求アイテムが見つかりませんでした。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター (JSON または XML)


名前	Description (説明)
エンタイトルメント	渡されたフィルター基準に一致するエンタイトルメントのリスト。データタイプ：オブジェクトのアレイ `"entitlements": [ { "account": "String", "consumer": "String", "contract": "String", "end_date": "String", "entitlement_name": "String" "household": "String", "product": "String", "product_offering": "String", "service_contract_line": "String", "sold_entitlement": "String", "start_date": "String", "state": "String", "sys_id": "String" } ]`
entitlements.account	このエンタイトルメントに関連付けられたアカウントレコードのSys_id。アカウント [customer_account] テーブルにあります。データタイプ：文字列
entitlements.consumer	このエンタイトルメントに関連付けられたコンシューマーレコードのSys_id。コンシューマー [csm_consumer] テーブルにあります。データタイプ：文字列
entitlements.contract	このエンタイトルメントに関連付けられた契約レコードのSys_id。契約 [sn_pss_core_service_contract] テーブルにあります。データタイプ：文字列
end_date	関連付けられたエンタイトルメントレコードの [終了日] フィールドの値。データタイプ：文字列
entitlements.entitlement_name	エンタイトルメントの名前。データタイプ：文字列
entitlements.household	このエンタイトルメントに関連付けられた世帯レコードのSys_id。世帯 [csm_household] テーブルにあります。データタイプ：文字列
entitlements.product	このエンタイトルメントに関連付けられた製品レコードのSys_id。製品モデル [cmdb_model] テーブルにあります。データタイプ：文字列
entitlements.product_offering	このエンタイトルメントに関連付けられた製品オファーレコードのSys_id。製品オファー [sn_prd_pm_product_offering] テーブルにあります。データタイプ：文字列
entitlements.service_contract_line	このエンタイトルメントに関連付けられたサービス契約品目レコードのSys_id。サービス契約品目 [sn_pss_core_service_contract_line] テーブルにあります。データタイプ：文字列
entitlements.sold_entitlement	このエンタイトルメントに関連付けられた販売済みエンタイトルメントレコードのSys_id。販売済み製品テーブル [sn_install_base_sold_product] テーブルにあります。データタイプ：文字列
entitlements.start_date	関連するエンタイトルメントレコードの [開始日] フィールドの値。データタイプ：文字列
entitlements.state	エンタイトルメントレコードのステータス。有効な値： active キャンセルドラフト期限切れ中断データタイプ：文字列
entitlements.sys_id	エンタイトルメントレコードのSys_id。エンタイトルメント [service_entitlement] テーブルにあります。データタイプ：文字列
エラー	発生したエラーについて説明します。データタイプ: オブジェクト `"error": { "detail": "String", "message": "String" }` エラー応答の例: エラーメッセージ: ページサイズ -20 は無効です。ページサイズは 1 〜 100 の整数である必要がありますエラー条件:無効な sysparm_limit パラメーターが渡されました。sysparm_limitパラメーターは 1 から 100 の範囲でなければなりません。エラーメッセージ: ページオフセット -23 が無効です。オフセットは 0 以上の整数である必要がありますエラー条件:無効な sysparm_offset パラメーターが渡されました。sysparm_offsetパラメーターは整数でなければなりません。エラーメッセージ:無効なクエリパラメーター - accnt エラー条件:無効なクエリパラメーター「accnt」が渡されました。パラメーターは「account」である必要があります。エラーメッセージ:無効な選択値:ステータス = drft エラー状態:無効な値「drft」が渡されました。パラメーター値は「draft」にする必要があります。
error.detail	エンドポイント呼び出しが失敗した理由に関する詳細情報。データタイプ：文字列
error.message	エラーの概要を説明するメッセージ。データタイプ：文字列
hasMore	返すエンタイトルメントレコードがまだあるかどうかを示すフラグ。有効な値： true:返されるエンタイトルメントレコードが増えます。 false:これ以上エンタイトルメントレコードはありません。データタイプ：ブーリアン
status	エンドポイントコールのステータス。有効な値： failure:要求の処理中にエラーが発生しました。 success:コールは正常に処理されました。データタイプ：文字列
sysparm_limit	sysparm_limitパラメーターがエンドポイント呼び出しで渡された場合は渡された値が含まれ、それ以外の場合はデフォルト値が含まれます。データタイプ：数値
sysparm_offset	sysparm_offsetパラメーターがエンドポイント呼び出しで渡された場合は渡された値が含まれ、それ以外の場合はデフォルト値が含まれます。データタイプ：数値

cURL 要求

次のコード例は、特定のアカウントのエンタイトルメントを返す方法を示しています。

curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

返される結果：

{
  "result": {
    "sysparm_offset": "0",
    "sysparm_limit": "10",
    "has_more": "false",
    "entitlements": [
      {
        "sys_id": "38374bf251e27110f877bf82d3ddf30a",
        "entitlement_name": "test ent",
        "account": "9e2fd2ee11b43110f877366201dea674",
        "consumer": null,
        "household": null,
        "contract": "0e1747f251e27110f877bf82d3ddf31c",
        "service_contract_line": "da278fb251e27110f877bf82d3ddf3b7",
        "state": "active",
        "product_offering": null,
        "sold_entitlement": null,
        "product": null,
        "start_date": "2023-11-21",
        "end_date": ""
      },
      {
        "sys_id": "e6ad4e4151723d10f877bf82d3ddf3fb",
        "entitlement_name": "tets entitlement",
        "account": "9e2fd2ee11b43110f877366201dea674",
        "consumer": null,
        "household": null,
        "contract": "0e1747f251e27110f877bf82d3ddf31c",
        "service_contract_line": "e79dce4151723d10f877bf82d3ddf31d",
        "state": "active",
        "product_offering": null,
        "sold_entitlement": null,
        "product": null,
        "start_date": "2023-11-21",
        "end_date": ""
      }
    ],
    "status": "success"
  }
}

cURL 要求

次のコード例は、特定のアカウントとサービス契約品目のエンタイトルメントを返す方法を示しています。

curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d&account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

返される結果：

{
  "result": {
    "sysparm_offset": "0",
    "sysparm_limit": "10",
    "has_more": "false",
    "entitlements": [
      {
          "sys_id": "e6ad4e4151723d10f877bf82d3ddf3fb",
          "entitlement_name": "test entitlement",
          "account": "9e2fd2ee11b43110f877366201dea674",
          "consumer": null,
          "household": null,
          "contract": "0e1747f251e27110f877bf82d3ddf31c",
          "service_contract_line": "e79dce4151723d10f877bf82d3ddf31d",
          "state": "active",
          "product_offering": null,
          "sold_entitlement": null,
          "product": null,
          "start_date": "2023-11-21",
          "end_date": ""
      }
    ],
    "status": "success"
  }
}

cURL 要求

次のコード例は、エラー応答を示しています。

curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

返される結果：

{
  "error": {
    "detail": "At least one of Account or Consumer parameter is mandatory.",
    "message": "At least one of Account or Consumer parameter is mandatory."
  },
  "status": "failure"
}

エンタイトルメントの検証:/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}

指定されたエンタイトルメント特性レコードとその最新の使用状況レコードの詳細を返します。

特性の最新の使用レコードは、期間の開始日が現在の日付以前で、期間の終了日が現在の日付以降のレコードとして定義されます。

URL 形式

バージョニングされた URL: /api/sn_ent_verify/v1/verifyentitlements/getEntitlementCharacteristic/{id}

デフォルト URL: /api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}

サポートされている要求パラメーター

表 : 7. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。たとえば、`v1` や `v2`。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列
id	返されるエンタイトルメント特性レコードのSys_id。エンタイトルメント特性 [sn_pss_core_entitlement_characteristic] テーブルにあります。データタイプ：文字列

表 : 8. クエリパラメーター
名前	説明
display_value	関連付けられたフィールド値、表示値、またはその両方を返すかどうかを示すフラグ。有効な値： true:応答にはフィールドの表示値のみが含まれます。例: `"state": "Draft"`。 false:応答にはフィールドの値のみが含まれます。例: `"state": "draft"`。 all:応答には、フィールドのすべての情報が含まれます。例： `"state": { "name": "state", "label": "State", "value": "draft", "display_value": "Draft", "type": "string" },` データタイプ：文字列デフォルト値：false

表 : 9. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

表 : 10. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。デフォルト： application/json

表 : 11. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

表 : 12. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
403	禁止されました。ユーザーには、指定されたレコードへのアクセス権がありません。
404	見つかりません。要求アイテムが見つかりませんでした。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター (JSON または XML)


名前	Description (説明)
特性	関連付けられたエンタイトルメント特性レコードのSys_id。特性 [sn_prd_pm_characteristic] テーブルにあります。データタイプ：文字列
characteristic_option	関連付けられた特性オプションレコードのSys_id。特性オプション [sn_prd_pm_characteristic_option] テーブルにあります。データタイプ：文字列
entitlement_usage	指定されたエンタイトルメント特性レコードに関連付けられたエンタイトルメント使用レコードに関する詳細。データタイプ：オブジェクトのアレイ `"entitlement_usage": [ { "entitlement_characteristic": "String", "period_end": "String, "period_start": "String", "sys_id": "String", "total_units": "String", "used_units": "String" } ]`
entitlement_usage。entitlement_characteristic	関連付けられたエンタイトルメント特性レコードのSys_id。エンタイトルメント特性 [sn_pss_core_entitlement_characteristic] テーブルにあります。データタイプ：文字列
entitlement_usage。period_end	エンタイトルメント使用状況レコードの期間終了フィールドの値。この値は、このエンタイトルメントの使用状況トラッキングが終了する日付です。データタイプ：文字列
entitlement_usage。period_start	エンタイトルメント使用状況レコードの期間開始フィールドの値。この値は、このエンタイトルメントの使用状況トラッキングが開始される日付です。データタイプ：文字列
entitlement_usage。sys_id	返されたエンタイトルメント使用状況レコードの Sys ID。エンタイトルメントの使用状況 [sn_pss_core_entitlement_usage] テーブルにあります。データタイプ：文字列
entitlement_usage。total_units	購入したユニットの合計数。エンタイトルメント使用状況レコードの [合計ユニット数] フィールドにあります。データタイプ：文字列
entitlement_usage。used_units	使用されたユニットの数。エンタイトルメント使用状況レコードの使用済みユニットフィールドにあります。データタイプ：文字列
sys_id	エンタイトルメント特性レコードの Sys ID。エンタイトルメント特性 [sn_pss_core_entitlement_characteristic] テーブルにあります。データタイプ：文字列
type	エンタイトルメント特性レコードのタイプフィールドの値。可能な値：対象範囲の拡大 coverage_and_usage データタイプ：文字列
値	特性を付与する範囲。一部の特性では、対象範囲は特性オプションテーブルで定義されます。ただし、[特性オプション] テーブルに補償が定義されていない場合は、 value パラメータで補償情報を渡すことができます。特性オプションは、以下の特性タイプに対してのみ定義されます。チェックボックス選択はい/いいえ他のすべてのタイプの特性では、 value パラメータに範囲値を含める必要があります。たとえば、特性が「置換回数」で、その補償が特性オプションテーブルで定義されていない場合、このパラメータで「10」、「20」などの補償を指定できます。注: このパラメータには、特性の最終的な対象範囲値が含まれます。[特性オプション] テーブルに情報がある場合は、このパラメーターに伝播されます。データタイプ：文字列

cURL 要求

次のコード例は、すべての既定値を使用してこのエンドポイントを呼び出す方法を示しています。

curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

返される結果：

{
  "result": {
    "sys_id": "3c817faa43823110341605ed0bb8f23a",
    "characteristic": "b73177aa43823110341605ed0bb8f246",
    "type": "coverage",
    "characteristic_option": "ff617baa43823110341605ed0bb8f266",
    "value": "Minor parts",
    "entitlement_usage": [
      {
        "sys_id": "03e3224d51b23d10f877bf82d3ddf310",
        "period_start": "2022-12-12",
        "period_end": "2025-12-12",
        "entitlement_characteristic": "3c817faa43823110341605ed0bb8f23a",
        "total_units": "10",
        "used_units": "5"
      }
    ]
  }
}

cURL 要求

次のコード例は、このエンドポイントを呼び出し、すべての表示値を返す方法を示しています。

curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a?display_value=all" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

返される結果：

{
  "result": {
    "sys_id": {
      "label": "Sys ID",
      "value": "3c817faa43823110341605ed0bb8f23a",
      "displayValue": "3c817faa43823110341605ed0bb8f23a",
      "type": "GUID"
    },
    "characteristic": {
      "name": "characteristic",
      "label": "Characteristic",
      "value": "b73177aa43823110341605ed0bb8f246",
      "display_value": "Repair parts covered",
      "type": "reference"
    },
    "type": {
      "name": "type",
      "label": "Type",
      "value": "coverage",
      "display_value": "Coverage",
      "type": "string"
    },
    "characteristic_option": {
      "name": "characteristic_option",
      "label": "Characteristic option",
      "value": "ff617baa43823110341605ed0bb8f266",
      "display_value": "Minor parts",
      "type": "reference"
    },
    "value": {
      "name": "value",
      "label": "Value",
      "value": "Minor parts",
      "display_value": "Minor parts",
      "type": "string"
    },
    "entitlement_usage": [
      {
        "sys_id": {
          "label": "Sys ID",
          "value": "03e3224d51b23d10f877bf82d3ddf310",
          "displayValue": "03e3224d51b23d10f877bf82d3ddf310",
          "type": "GUID"
        },
        "period_start": {
          "name": "period_start",
          "label": "Period start",
          "value": "2022-12-12",
          "display_value": "2022-12-12",
          "type": "glide_date"
        },
        "period_end": {
          "name": "period_end",
          "label": "Period end",
          "value": "2025-12-12",
          "display_value": "2025-12-12",
          "type": "glide_date"
        },
        "entitlement_characteristic": {
          "name": "entitlement_characteristic",
          "label": "Entitlement characteristic",
          "value": "3c817faa43823110341605ed0bb8f23a",
          "display_value": "Repair parts covered",
          "type": "reference"
        },
        "total_units": {
          "name": "total_units",
          "label": "Total units",
          "value": "10",
          "display_value": "10",
          "type": "string"
        },
        "used_units": {
          "name": "used_units",
          "label": "Used units",
          "value": "5",
          "display_value": "5",
          "type": "string"
        }
      }
    ]  
  }
}