JSON データ検索 API
インスタンスに HTTPS GET 要求を発行して、データをクエリします。
sysparm_sys_id パラメーターが存在する場合、デフォルトでは、GET 要求は get 関数として解釈されます。それ以外の場合は、getRecords 関数として解釈されます。URL パラメーター sysparm_action=get を指定することもできます。クエリ応答は常にレコードのレコードハッシュによってカプセル化され、個々のレコードの値自体がフィールド名によってハッシュされます。
参照変数の表示値を返す
get または getRecords 関数からレコードを取得すると、そのレコードに関連付けられたすべてのフィールドが返されます。多くの場合、フィールドは別のテーブルの
sys_id を含む参照フィールドです。ベースシステムの動作では、これらのフィールドの sys_id 値が返されます。フィールドの表示値を返すには、次のいずれかのオプションを使用します。- プロパティ glide.json.return_displayValue をシステムプロパティに追加すると、すべての JSON 要求が参照フィールドの表示値を返します。
- パラメーター displayvalue=true を JSON 要求 URL に追加すると、そのパラメーターを含む JSON 要求は、参照フィールドの
sys_idの代わりに表示値を返します。JSON URL は次のようになります。https://<instance name>.service-now.com/incident.do?JSON&sysparm_action=getRecords&sysparm_query=active=true^category=hardware&displayvalue=true - パラメーター displayvalue=all を JSON 要求 URL に追加すると、そのパラメーターを含む JSON 要求は、参照フィールドの表示値と
sys_idを返します。表示値フィールドの応答要素名には、dv_caller_idのように、dv_というプリフィックスが付きます。
変数の取得
displayvariables クエリパラメーターを使用して、サービスカタログ アイテムレコードに関連付けられた変数のアレイを返します。変数を取得するには、JSON 要求 URL にパラメーター displayvariables=true を追加します。たとえば、サービスカタログ 変数を含む JSON 形式のレコードを取得する URL は次のとおりです。
https://<your-instance>.servicenow.com/sc_req_item.do?JSONv2&sysparm_action=getRecords&sysparm_query=sys_id=5018da81742bd410f8771974894916fe&displayvariables=true次に示すのは、レコードから複数行の変数セットを表示する応答の例です。
{
"records":[
{
…
"variables":[
{
"display_value":[
{
"quantity":"1",
"color":"Black",
"device_type":"Apple iPhone 8",
"storage":"64GB"
},
{
"quantity":"1",
"color":"Black",
"device_type":"Apple iPhone 8",
"storage":"64GB"
}
],
"columns_meta":[
{
"name":"device_type",
"label":"Device Type",
"id":"da7d3f3241411300964ff05369414eca",
"type":5,
"order":"0"
},
{
"name":"storage",
"label":"Storage",
"id":"691e337241411300964ff05369414e31",
"type":5,
"order":"1"
},
{
"name":"color",
"label":"Color",
"id":"e89fb77241411300964ff05369414e74",
"type":5,
"order":"2"
},
{
"name":"quantity",
"label":"Quantity",
"id":"2d5f737241411300964ff05369414eaf",
"type":5,
"order":"3"
}
],
"max_rows":50,
"name":"mobile_devices_set",
"id":"e84d3f3241411300964ff05369414e3e",
"type":"one_to_many",
"value":[
{
"quantity":"1",
"color":"black",
"device_type":"iphone8",
"storage":"64GB"
},
{
"quantity":"1",
"color":"black",
"device_type":"iphone8",
"storage":"64GB"
}
],
"row_count":2
},
{
"question_text":"Department",
"name":"department",
"type":8,
"value":"Development",
"order":100
},
{
"question_text":"Who is this request for?",
"name":"requested_for",
"type":8,
"value":"System Administrator",
"order":100
},
{
"question_text":"When do you need this?",
"name":"needed_by",
"type":5,
"value":"Today",
"order":200
},
{
"question_text":"Business Justification",
"name":"business_justification",
"type":2,
"value":"Example justification",
"order":200
}
],
…
}
]
}応答のキーは次のように定義されます。
| キー | 説明 |
|---|---|
| display_value | 複数行の変数セットの質問の表示値。複数行の変数セットでのみ返されます。 |
| columns_meta | フィールドの sys_id や name など、複数行の変数セットのメタデータのアレイ。変数に複数のフィールドが含まれている場合にのみ返されます。 |
| max_rows | 複数行の変数セットで許可される最大行数。複数行の変数セットでのみ返されます。 |
| name | 質問の名前。 |
| id | 複数行の変数セットの sys_id。複数行の変数セットでのみ返されます。 |
| type | 質問のタイプ。 |
| value | 質問の値。 |
| row_count | 複数行の変数セット内の現在の行数。複数行の変数セットでのみ返されます。 |
| question_text | 質問のラベル。単一行の変数セットでのみ返されます。 |
| order | 質問の順序。 |
レコードの順序の制御
JSON 応答に表示されるレコードの順序を制御できます。順序を設定するには、URL エンコードクエリで ORDERBY または ORDERBYDESC 節を使用します。例を次に示します。
sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategoryこの例では、すべてのアクティブなレコードをフィルタリングし、最初に結果を番号で昇順に並べ替えた後、カテゴリで降順に並べ替えます。詳細については、「 エンコードされたクエリ文字列」を参照してください。
getKeys
sysparm_query パラメーターでエンコードされたクエリ文字列を指定して、複数のレコードの
sys_id を取得します。https://<instance name>.service-now.com/incident.do?JSONv2&sysparm_action=getKeys&sysparm_query=active=true^category=hardware
get
sysparm_sys_id パラメーターで
sys_id を指定して、レコードを直接取得します。https://<instance name>.service-now.com/incident.do?JSONv2&sysparm_sys_id=9d385017c611228701d22104cc95c371
必要に応じて、sysparm_action パラメーターを指定することもできます。
https://<instance name>.service-now.com/incident.do?JSONv2&sysparm_action=get&sysparm_sys_id=9d385017c611228701d22104cc95c371
getRecords
sysparm_query パラメーターでエンコードされたクエリ文字列を指定して、すべてのレコードを取得します。
https://<instance name>.service-now.com/incident.do?JSONv2&sysparm_action=getRecords&sysparm_query=active=true^category=hardware