Boxクエリ

BoxクエリAPIを使用すると、Box内のオブジェクトを検索して見つけることができます。メタデータテンプレートや項目フィールドを使用して、結果にフィルタをかけたり、並べ替えたりできるため、詳細なクエリを作成できます。基本的なファイルおよびフォルダの検索にとどまらない、さまざまな種類のBoxの項目に対応しています。クエリを作成するには、クエリの詳細を指定してPOST https://api.box.com/2.0/queryエンドポイントを呼び出します。

パラメータ

コールを実行するには、以下のパラメータを渡す必要があります。必須のパラメータは太字で示されています。

パラメータ	型	説明	例
`query.predicate`	string	クエリのフィルタはSQLに似た構文で指定します。値には`:parameter`プレースホルダを使用します。メタデータテンプレートフィールドとでサポートされている演算子を参照してください。	`"amount >= :value"`
`query.params`	object	述語の各`:placeholder`の値。各キーは、プレースホルダ名から`:`を除いた値と一致します。値のタイプが述語フィールドと一致する必要があります。	`{ "value": 100 }`
`query.ancestors`	array	結果を、特定の先祖およびそのサブ項目の中の項目に制限します。各オブジェクトに`id`および`type` (`folder`など) が必要です。指定するすべての先祖に対する読み取りアクセスが必要です。	`[{ "id": "123", "type": "folder" }]`
`query.order_by`	array	結果を並べ替える方法。各オブジェクトに`field_key`および`direction` (`asc`または`desc`) が必要です。複数のフィールドを使って並べ替えるには、複数のオブジェクトを追加します。	`[{ "field_key": "box:item:created_at", "direction": "desc" }]`
`limit`	integer	返される結果の数の上限。デフォルト値は50です。0～100の値を指定してください。	`50`
`fields`	array	それぞれの結果に格納する追加フィールド。デフォルトでは、項目のタイプとIDのみが結果に含まれます。それぞれの値は項目フィールドキー、あるいはメタデータテンプレートまたはフィールドキーになります。	`["box:item:created_at", "enterprise_123:templateKey:someField"]`
`marker`	string	結果の次のページを取得するための、以前の応答に含まれるトークン。直前のリクエストを続行し、他のすべてのパラメータを同じ値に維持する場合にのみ使用してください。	`"AAAAAmVYB1FWec8GH6..."`

例

2つのカスタムメタデータテンプレートに対するクエリ:

{
"query": {
	"predicate": "enterprise_12345678:contract:status = :contractStatus AND
enterprise_12345678:project:inceptionDate >= :date",
	"params": {
		"contractStatus": "Signed",
		"date": "2020-01-01T00:00:00Z"
	},
},
"order_by": [
{
	"field_key": "enterprise_12345678:project:projectId",
	"direction": "asc"
	},
	],
	"limit": 10,
	"include_total_count": true,
	"fields": [
		"box:item:name",
		"enterprise_12345678:project"
	]
}

1つのカスタムメタデータテンプレートと項目情報に対するクエリ:

{
"query": {
	"predicate": "enterprise_12345678:inventory:book:purchasePrice >= :p1 AND
box:item:name = :name",
	"params": {
		"p1": 100,
		"name": "The Hobbit"
	},
	"ancestors": [
		"folder_789"
	],
},
"order_by": [
	{
		"field_key": "enterprise_12345678:inventory:book:purchasePrice",
		"direction": "asc"
	},
],
"limit": 1,
"include_total_count": true,
"fields": [
	"box:item:name",
	"enterprise_12345678:book"
	]
}

レスポンス

{
	"entries": [
		{
			"id": "12345",
			"type": "file",
			"box": {
				"item": {
					"name": "My Form"
				},
			},
		"enterprise_12345678": {
			"book": {
				"$id": "82ba3e97-496c-475d-85f2-078c690c434c",
				"$parent": "file_12345",
				"$scope": "enterprise_12345678",
				"$template": "book",
				"$type": "book-b52189dd-caa3-44e9-ba36-d31079bb10e6",
				"isbn": "1871263670",
				"purchasePrice": 234.57,
				"publicationYear": "1937"
			}
		}
	}
	],
	"next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=A="
}

レスポンスのフィールド

フィールド	型	説明
`entries`	array	クエリに一致する項目のリスト。各オブジェクトに、述語に一致する1つの項目のタイプとIDが含まれます。リクエストで`fields`パラメータが指定されている場合、追加の項目フィールドとメタデータフィールドが提供されます。
`next_marker`	stringまたはnull	結果の次のページを取得するために使用できるトークン。それ以上の結果がない場合、この値はnullになります。それ以上の結果がある場合には、この値を`marker`パラメータとしてフォローアップリクエストに指定することで、追加のエントリを取得できます。

ページネーションではスナップショットではなくマーカーが使用されます。すべてのページを統合すると、一致する全項目が記載されたリストを一度に取得できない場合があります。開始後に新しい一致が表示される場合があり、さらに結果の取得中に前のページに含まれる項目が変更または削除されると、以降のページでその項目がなくなる可能性があります。

エラーコード

エラーコード	エラータイプ	エラーメッセージ
`400`	`UNEXPECTED_JSON_TYPE`	Expected JSON with type string. (文字列型のJSONを想定しています。)
`400`	`INVALID_QUERY`	Failed to parse query: Unexpected end of input. (クエリを解析できませんでした: 予期しない入力終了。)
`400`	`INVALID_QUERY`	Scope is invalid. (スコープが無効です。)
`401`	`UNAUTHORIZED`	The provided access token is invalid. (指定されたアクセストークンが無効です。)
`403`	`FORBIDDEN`	Query API found either too many items or too many inaccessible items matching the query. (クエリAPIで、クエリに一致する項目数が多すぎるか、アクセスできない項目が多すぎることが検出されました。)
`404`	`INSTANCE_NOT_FOUND`	The templates you referenced were not found. (参照されているテンプレートが見つかりません。)
`404`	`ITEM_NOT_FOUND`	Item not found. (項目が見つかりません。)
`500`	`INTERNAL_SERVER_ERROR`	Internal server error. (内部サーバーエラー。)

はじめに

アプリケーションと統合

IDとアクセス

APIの利用

トラブルシューティング

コンテンツ

コラボレーション

メタデータと検索

イベントとWebhook

ユーザー

インテリジェントなワークフロー

電子サイン

セキュリティとコンプライアンス

パラメータ

例

レスポンス

レスポンスのフィールド

エラーコード

​パラメータ

​例

​レスポンス

​レスポンスのフィールド

​エラーコード

パラメータ

例

レスポンス

レスポンスのフィールド

エラーコード