パラメータの問合せ

言語:

一部のリクエストでは、返されるデータを変更または拡張するオプションの問合せパラメータを取ります。詳細については、各リソースのドキュメントを参照してください。すべてのリソースがすべての問合せパラメータをサポートしているわけではありません。このセクションでは、リソースが指定された問合せパラメータを実装する場合に使用される一般的な問合せパラメータについてのみ説明します。

表 2 一般的な問合せパラメータ

パラメータ	説明
props=true	リソースのプロパティーメタデータを一覧表示します (デフォルトは false)
limit=`n`	返されるリスト要素の数を制限します
start=`n`	返される要素データの開始に使われるインデックス番号 (または時間)
depth=`n`	返されるデータの詳細レベルを指定するインデックス番号
match_`Property-Name`=`Value`	指定されたプロパティー名と値に一致するデータを一覧表示します

問合せパラメータ: props

props 問い合わせパラメータは GET、POST、PUT の各コマンドで使用可能であり、エンドユーザーがメタデータにアクセスできるようにします。エンドユーザーからこの機能を要求するには、問い合わせパラメータ props を true に設定します。GET 操作と PUT 操作の場合、返された JSON オブジェクトには、要求したデータのほかに、プロパティーのメタデータのリストが含まれています。POST の場合、ユーザーがリソースを適切に作成することを支援するメタデータのみが返されます。

表 3 プロパティーメタデータ値

プロパティー	説明
name	プロパティー名
label	プロパティーの説明
immutable	プロパティーを変更できないことを示すフラグ
type	プロパティーの型: String、Integer、Boolean...
choices	列挙されたプロパティーの場合、使用可能な値の配列

問合せパラメータ: limit

limit 問合せは、返される要素の最大数を制限するために、多数の要素を返す可能性のある多くの GET コマンドで使用できます。

問合せパラメータ: start

start 問合せパラメータは、limit パラメータをサポートする同じコマンドでサポートされています。返されるデータの開始に使用される開始インデックスを指定します。時間値をサポートするリソースの場合、インデックスは「20130531T01:13:58」などの時間値になることがあります。

問い合わせパラメータ: depth

depth 問い合わせパラメータは、リソースのリストを取得するために GET コマンドで使用できます。これは、返されるリストの詳細レベルを指定するために使用します。depth の数値が大きいほど、より詳しい情報が返されます。

問い合わせパラメータ depth を使用したリクエストの例:

GET /api/user/v1/users?depth=2 HTTP/1.1                    
Host: zfs-storage.example.com
X-Auth-User: root
X-Auth-Key: letmein-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": "DummyPassword",
		"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": "tom",
	"properties": {
		"logname": "tom",
		"fullname": "Tommy",
		"initial_password": "DummyPassword",
		"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/tom"
    }]
}

問い合わせパラメータ: match

match_Property-Name=Value 問い合わせパラメータは、リソースのリストを取得するために GET コマンドで使用できます。指定されたプロパティー名と値に一致するデータのリストが返されます。