Box Developerドキュメント
ログイン

Request extra fields

ガイド APIコール Request extra fields

Request extra fields

The number of fields returned for a resource depends on the API endpoint used to request the resource.

Use the fields query parameter

標準のレスポンスにデフォルトでは含まれない、リソースの特定のフィールドをリクエストするには、fieldsクエリパラメータをリクエストに追加します。このパラメータの値は、フィールド名のコンマ区切りリストです。

curl https://api.box.com/2.0/files/12345?fields=is_package,lock \
    -H "authorization: Bearer ACCESS_TOKEN"


{
  "etag": "1",
  "id": "12345",
  "is_package": false,
  "lock": null,
  "type": "file"
}

It is important to note that when a specific field is requested no other fields are returned except for those requested and the base set of fields. For a file, this base set is comprised of the etag, id, and type values.

Resource variants

The following resource variants are available in the Box API.

Standard

The default set of fields returned in an API response. The standard variant is returned when requesting a resource through the main APIs available for that resource. For example, when requesting the GET /files/:id endpoint the API will return the standard variation of a file.

curl https://api.box.com/2.0/files/12345 \
    -H "authorization: Bearer ACCESS_TOKEN"


{
    "content_created_at": "2019-06-20T06:04:41-07:00",
    "content_modified_at": "2019-06-20T06:04:41-07:00",
    "created_at": "2019-06-20T07:28:42-07:00",
    "created_by": {
        "id": "191919191",
        "login": "joe@example.com",
        "name": "Joe Box",
        "type": "user"
    },
    "description": "",
    "etag": "1",
    "file_version": {
        "id": "56663434454334",
        "sha1": "585afa5209bbd586c79499b7336601341ad06cce",
        "type": "file_version"
    },
    "id": "12345",
    ...
    "size": 65000647,
    "trashed_at": null,
    "type": "file"
}

Mini

別のレスポンスのネストされた部分としてリソースが返される場合は、サイズが縮小され、重要なフィールドの一部のみが返されることがよくあります。このバリアントは、一般に簡易リソースバリアントと呼ばれます。

たとえば、GET /folders/:id/itemsエンドポイントをリクエストすると、APIはitem_collection内でネストされたファイルとフォルダの簡易バリエーションを返します。

curl https://api.box.com/2.0/files/12345 \
    -H "authorization: Bearer ACCESS_TOKEN"


{
  "id": "0",
  "type": "folder",
  "item_collection": {
    "entries": [
      {
        "etag": "1",
        "file_version": {
          "id": "56663434454334",
          "sha1": "585afa5209bbd586c79499b7336601341ad06cce",
          "type": "file_version"
        },
        "id": "12345",
        "name": "Video.mp4",
        "sequence_id": "1",
        "sha1": "585afa5209bbd586c79499b7336601341ad06cce",
        "type": "file"
      }
      ...
    ]
    ...
  }
  ...
}

ネストされたリソースの詳細をリクエストするには、そのリソースに対してAPIを呼び出して、IDでそのリソースをリクエストすることをお勧めします。その際、オプションでfieldクエリパラメータを渡すこともできます。

たとえば、フォルダ内の項目のリストを取得するときに返されるファイルの所有者を取得する場合は、クエリパラメータfield=owned_byを指定して、IDでそのファイルをリクエストします。

Full

The total set of fields that can be returned in an API response. The full variant is returned when requesting a resource through the main APIs available for that resource and by appending the fields query parameter.

たとえば、fields=is_package,lockパラメータを指定してGET /files/:idエンドポイントをリクエストすると、APIは、指定されたフィールドに加えて、そのファイルの基本的なフィールドを返します。

curl https://api.box.com/2.0/files/12345?fields=is_package,lock \
    -H "authorization: Bearer ACCESS_TOKEN"


{
  "etag": "1",
  "id": "12345",
  "is_package": false,
  "lock": null,
  "type": "file"
}