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

ガイド API呼び出し 追加フィールドのリクエスト

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

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

バリアント
標準GET /files/:idエンドポイントを介してファイルをリクエストする場合など、リソースを固有のエンドポイントに対してリクエストしたときに返される標準のフィールドセット
詳細fieldクエリパラメータを使用して、リソースの固有のエンドポイントを介して返すことができる詳細なフィールドセット
簡易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"
}

特定のフィールドがリクエストされると、リクエストされたフィールドとフィールドの「基本」のフィールド以外のフィールドが返されない点に注意してください。ファイルの場合、この基本セットはetagid、および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"
}