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

ワシントンDC API リファレンス

Release

washingtondc

ft:locale

ja-JP

ft:publication_title

ワシントンDC API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

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

リリースバージョン: Washingtondc

更新日 2024年02月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 = boxeoAND 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 or consumer パラメーターのいずれかを渡す必要があります。これらは相互に排他的です。エンタイトルメントレコードを返すアカウントレコードSys_id。アカウント [customer_account] テーブルにあります。データタイプ：文字列デフォルト：なし
consumer	account or 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]" テーブルを検索し、関連するインストールベースでカバーされているすべてのエンタイトルメントを返します。データタイプ：文字列デフォルト：なし
製品	エンタイトルメントレコードを返す対象の製品レコード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]" テーブルを検索し、関連する販売済み製品の対象となるすべての資格付与を返します。データタイプ：文字列デフォルト：なし
ステータス	返却するエンタイトルメントのステータス。有効な値：アクティブキャンセルドラフト期限切れ中断データタイプ：文字列デフォルト：すべて

表 : 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)


名前	説明
資格	合格したフィルター基準に一致するエンタイトルメントのリスト。データタイプ：オブジェクトのアレイ `"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	エンタイトルメントレコードのステータス。有効な値：アクティブキャンセルドラフト期限切れ中断データタイプ：文字列
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」にする必要があります。エラーメッセージ:無効な選択値:state = 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)


名前	説明
特性	関連付けられたエンタイトルメント特性レコードの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] テーブルにあります。データタイプ：文字列
タイプ	資格付与特性レコードのタイプフィールドの値。可能な値：対象範囲の拡大 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"
        }
      }
    ]  
  }
}