一部のリクエストでは、返されるデータを変更または拡張する、オプションの問合せパラメータを取ります。詳細については、各リソースのドキュメントを参照してください。すべてのリソースがすべての問合せパラメータをサポートしているわけではありません。このセクションでは、リソースが指定された問合せパラメータを実装する場合に使用される一般的な問合せパラメータについてのみ説明します。
|
props 問合せパラメータは GET、POST、PUT の各コマンドで使用可能であり、エンドユーザーがメタデータにアクセスできるようにします。エンドユーザーからこの機能を要求するには、問合せパラメータ props を true に設定します。GET 操作と PUT 操作の場合、返された JSON オブジェクトには、要求したデータのほかに、プロパティーのメタデータのリストが含まれています。POST の場合、ユーザーがリソースを適切に作成することを支援するメタデータのみが返されます。
|
limit 問合せは、返される要素の最大数を制限するために、多数の要素を返す可能性のある多くの GET コマンドで使用できます。
時間値をサポートするリソースの場合、index が 20170531T01:13:58 などの時間値になることがあり、UTC 時間で表記する必要があります。
depth 問合せパラメータは、リソースのリストを取得するために GET コマンドで使用できます。これは、返されるリストの詳細レベルを指定するために使用します。depth の数値が大きいほど、より詳しい情報が返されます。例:
/api/...?depth=0 – ノードのプロパティーと子の名前のみを返します。
/api/...?depth=1 – ノードのプロパティー、子の名前とプロパティー、孫の名前のみを返します。
/api/...?depth=2 – ノードのプロパティー、子の名前とプロパティー、孫の depth=0 出力を返します。
問合せパラメータ depth を使用したリクエストの例:
GET /api/user/v1/users?depth=2 HTTP/1.1 Host: zfs-storage.example.com X-Auth-User: root X-Auth-Key: password-xxx
この例では、ユーザーのリストが depth=2 までの詳細度で返されます。
レスポンスの例:
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1558
X-Zfssa-Access-Api: 1.0
{"users":
[{
"name": "root",
"properties": {
"logname": "root",
"fullname": "Super-User",
"initial_password": "password",
"require_annotation": false
},
"children": [{
"name": "preferences",
"properties": {
"locale": "C",
"login_screen": "status/dashboard",
"session_timeout": 15,
"advanced_analytics": false
},
"children": [{
"name": "keys",
"properties": {},
"children": [],
"list": []
}],
"list": []
}],
"list": [],
"href": "/api/user/v1/users/root"
},
{
"name": "admin2",
"properties": {
"logname": "admin2",
"fullname": "Administrator",
"initial_password": "password",
"require_annotation": false,
"roles": ["basic"],
"kiosk_mode": false,
"kiosk_screen": "status/dashboard"
},
"children": [{
"name": "exceptions",
"properties": {},
"children": [],
"list": [{
"name": "auth-000",
"properties": {
"scope": "stat",
"drilldowns": "*",
"allow_create": false,
"allow_read": true
},
"children": [],
"list": []
},
{
"name": "auth-001",
"properties": {
"scope": "ad",
"name": "*",
"allow_domain": true,
"allow_workgroup": false
},
"children": [],
"list": []
}]
}, {
"name": "preferences",
"properties": {
"locale": "C",
"login_screen": "status/dashboard",
"session_timeout": 15,
"advanced_analytics": false
},
"children": [{
"name": "keys",
"properties": {},
"children": [],
"list": ["key-000"]
}],
"list": []
}],
"list": [],
"href": "/api/user/v1/users/admin2"
}]
}
match_property-name=value 問合せパラメータは、リソースのリストを取得するために GET コマンドで使用できます。これは、指定されたプロパティー名と値に一致するデータのリストを返します。例:
/api/...?depth=0&match_kiosk_mode=true – kiosk_mode が true の場合のフィルタ済みリストと子の名前を返します。
/api/...?depth=1&match_kiosk_mode=true – kiosk_mode が true の場合のフィルタ済みリストと depth=1 までの詳細を返します。
/api/...?depth=2&match_Fullname='Super*'&kiosk_mode=true – fullname に Super を含み、kiosk_mode が true の場合のフィルタ済みリストと、depth=2 までの詳細を返します。