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

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

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

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

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

fieldsクエリパラメータの使用

標準のレスポンスにデフォルトでは含まれない、リソースの特定のフィールドをリクエストするには、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"
}

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

リソースバリアント

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

Standard

APIレスポンスで返されるデフォルトのフィールドセットです。Standardバリアントは、リソースに対して使用できるメインの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"
}

Mini

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

APIレスポンスで返すことができるフィールドセット全体です。Fullバリアントは、リソースに対して使用できるメインの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"
}