질의 매개변수

언어:

일부 요청은 반환된 데이터를 수정하거나 개선할 선택적 질의 매개변수를 사용합니다. 자세한 내용은 각 리소스에 대한 설명서를 참조하십시오. 모든 리소스에서 모든 질의 매개변수를 지원하는 것은 아닙니다. 이 절에서는 리소스가 지정된 질의 매개변수를 구현할 때 사용될 일반 질의 매개변수에 대해서만 설명합니다.

표 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 명령에 사용하여 리소스 목록을 검색할 수 있습니다. 지정된 등록 정보 이름 및 값과 일치하는 데이터 목록이 반환됩니다.