追加フィールドのリクエスト

ガイド APIコール 追加フィールドのリクエスト

追加フィールドのリクエスト

リソースに対して返されるフィールドの数は、リソースのリクエストに使用されるAPIエンドポイントに応じて異なります。

バリアント
Standard	`GET /files/:id`エンドポイントを介してファイルをリクエストする場合など、リソースを固有のエンドポイントに対してリクエストしたときに返される標準のフィールドセット
Full	`field`クエリパラメータを使用して、リソースの固有のエンドポイントを介して返すことができる詳細なフィールドセット
Mini	`GET /folders/:id/items`エンドポイントを介してフォルダ内にあるすべての項目をリクエストしたときにファイルが返される場合など、リソースが別のリソースのネストされた部分として返されたときに返されるフィールドのサブセット

APIリファレンスドキュメントでは、このようにラベルの付いたバリエーションを詳しく説明しています。特に、ファイル、フォルダ、ウェブリンク、およびユーザー項目には詳細と簡易というバリエーションがあります。

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

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"
}

特定のフィールドがリクエストされると、リクエストされたフィールドとフィールドの「基本」のフィールド以外のフィールドが返されない点に注意してください。ファイルの場合、この基本セットはetag、id、およびtype値で構成されます。

以下のリソースバリアントは、BoxのAPIで使用できます。

APIレスポンスで返されるデフォルトのフィールドセットは、一般に、標準リソースバリアントと呼ばれます。通常、リソースに対して使用できるメインのAPIを介してそのリソースがリクエストされたときに返されます。たとえば、GET /files/:idエンドポイントをリクエストすると、APIはファイルの標準バリエーションを返します。

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"
}

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

たとえば、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でそのファイルをリクエストします。

APIレスポンスで返すことができるフィールドセット全体は、一般に、詳細リソースバリアントと呼ばれます。通常、リソースに対して使用できるメインのAPIを介し、fieldsクエリパラメータを追加してそのリソースをリクエストしたときに返されます。

たとえば、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"
}

追加フィールドのリクエスト

追加フィールドのリクエスト

フィールドクエリパラメータの使用

リソース

Standard

Mini

Full

関連するAPI