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

Box Developerドキュメントの新しいベータ版サイトがまもなくリリースされる予定です。最新の開発者向けガイド、APIリファレンス、AI搭載の検索により、Boxを使用した迅速な開発をサポートします。更新情報については今しばらくお待ちください。

項目のメタデータの更新

ガイド メタデータ メタデータインスタンス 項目のメタデータの更新

必須のガイド

項目のメタデータの更新

ファイルまたはフォルダに適用されたメタデータを更新するには、項目のid、テンプレートのtemplateKeyとscopeに加え、テンプレートインスタンスのデータを操作するための一連のJSON操作を使用します。

ファイルのメタデータの更新

ファイルのメタデータを更新するには、ファイルのfile_id、テンプレートのscopeとtemplateKey、およびテンプレートインスタンスのデータを操作するための一連のJSON操作を指定してPUT /files/:file_id/metadata/:scope/:templateKey APIエンドポイントを呼び出します。

cURL
curl -i -X PUT "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json-patch+json" \
     -d '[
        {
          "op": "test",
          "path": "/competitiveDocument",
          "value": "no"
        },
        {
          "op": "remove",
          "path": "/competitiveDocument"
        },
        {
          "op": "test",
          "path": "/status",
          "value": "active"
        },
        {
          "op": "replace",
          "path": "/status",
          "value": "inactive"
        },
        {
          "op": "test",
          "path": "/author",
          "value": "Jones"
        },
        {
          "op": "copy",
          "from": "/author",
          "path": "/editor"
        },
        {
          "op": "test",
          "path": "/currentState",
          "value": "proposal"
        },
        {
          "op": "move",
          "from": "/currentState",
          "path": "/previousState"
        },
        {
          "op": "add",
          "path": "/currentState",
          "value": "reviewed"
        }
      ]'
Node/TypeScript v10
await client.fileMetadata.updateFileMetadataById(
  file.id,
  'enterprise' as UpdateFileMetadataByIdScope,
  templateKey,
  [
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/name',
      value: 'Jack',
    } satisfies UpdateFileMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/age',
      value: 24,
    } satisfies UpdateFileMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/birthDate',
      value: '2000-01-03T02:20:50.520Z',
    } satisfies UpdateFileMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/countryCode',
      value: 'CA',
    } satisfies UpdateFileMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/sports',
      value: ['football'],
    } satisfies UpdateFileMetadataByIdRequestBody,
  ],
);
Python v10
client.file_metadata.update_file_metadata_by_id(
    file.id,
    UpdateFileMetadataByIdScope.ENTERPRISE,
    template_key,
    [
        UpdateFileMetadataByIdRequestBody(
            op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
            path="/name",
            value="Jack",
        ),
        UpdateFileMetadataByIdRequestBody(
            op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE, path="/age", value=24
        ),
        UpdateFileMetadataByIdRequestBody(
            op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
            path="/birthDate",
            value="2000-01-03T02:20:50.520Z",
        ),
        UpdateFileMetadataByIdRequestBody(
            op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
            path="/countryCode",
            value="CA",
        ),
        UpdateFileMetadataByIdRequestBody(
            op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
            path="/sports",
            value=["football"],
        ),
    ],
)
.NET v10
await client.FileMetadata.UpdateFileMetadataByIdAsync(fileId: file.Id, scope: UpdateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24 },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }}));
Java v10
client.getFileMetadata().updateFileMetadataById(file.getId(), UpdateFileMetadataByIdScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/name").value("Jack").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/age").value(24L).build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/birthDate").value("2000-01-03T02:20:50.520Z").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/countryCode").value("CA").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/sports").value(Arrays.asList("football")).build()))
.NET v6
await client.FileMetadata.UpdateFileMetadataByIdAsync(fileId: file.Id, scope: UpdateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24 },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }}));
Node v4
await client.fileMetadata.updateFileMetadataById(
  file.id,
  'enterprise' as UpdateFileMetadataByIdScope,
  templateKey,
  [
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/name',
      value: 'Jack',
    } satisfies UpdateFileMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/age',
      value: 24,
    } satisfies UpdateFileMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/birthDate',
      value: '2000-01-03T02:20:50.520Z',
    } satisfies UpdateFileMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/countryCode',
      value: 'CA',
    } satisfies UpdateFileMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/sports',
      value: ['football'],
    } satisfies UpdateFileMetadataByIdRequestBody,
  ],
);

認証済みユーザーがファイルのメタデータに対する変更を書き込めるようにするには、ファイルへの書き込みアクセス権限が必要です。

フォルダのメタデータを更新

フォルダのメタデータを更新するには、フォルダのfolder_id、テンプレートのscopeとtemplateKey、およびテンプレートインスタンスのデータを操作するための一連のJSON操作を指定してPUT /folders/:folder_id/metadata/:scope/:templateKey APIエンドポイントを呼び出します。

cURL
curl -i -X PUT "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json-patch+json" \
     -d '[
        {
          "op": "test",
          "path": "/competitiveDocument",
          "value": "no"
        },
        {
          "op": "remove",
          "path": "/competitiveDocument"
        },
        {
          "op": "test",
          "path": "/status",
          "value": "active"
        },
        {
          "op": "replace",
          "path": "/status",
          "value": "inactive"
        },
        {
          "op": "test",
          "path": "/author",
          "value": "Jones"
        },
        {
          "op": "copy",
          "from": "/author",
          "path": "/editor"
        },
        {
          "op": "test",
          "path": "/currentState",
          "value": "proposal"
        },
        {
          "op": "move",
          "from": "/currentState",
          "path": "/previousState"
        },
        {
          "op": "add",
          "path": "/currentState",
          "value": "reviewed"
        }
      ]'
Node/TypeScript v10
await client.folderMetadata.updateFolderMetadataById(
  folder.id,
  'enterprise' as UpdateFolderMetadataByIdScope,
  templateKey,
  [
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/name',
      value: 'Jack',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/age',
      value: 24,
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/birthDate',
      value: '2000-01-03T02:20:50.520Z',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/countryCode',
      value: 'CA',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/sports',
      value: ['football'],
    } satisfies UpdateFolderMetadataByIdRequestBody,
  ],
);
Python v10
client.folder_metadata.update_folder_metadata_by_id(
    folder.id,
    UpdateFolderMetadataByIdScope.ENTERPRISE,
    template_key,
    [
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/name",
            value="Jack",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/age", value=24
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/birthDate",
            value="2000-01-03T02:20:50.520Z",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/countryCode",
            value="CA",
        ),
        UpdateFolderMetadataByIdRequestBody(
            op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
            path="/sports",
            value=["football"],
        ),
    ],
)
.NET v10
await client.FolderMetadata.UpdateFolderMetadataByIdAsync(folderId: folder.Id, scope: UpdateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24 },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }}));
Java v10
client.getFolderMetadata().updateFolderMetadataById(folder.getId(), UpdateFolderMetadataByIdScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/name").value("Jack").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/age").value(24L).build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/birthDate").value("2000-01-03T02:20:50.520Z").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/countryCode").value("CA").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/sports").value(Arrays.asList("football")).build()))
.NET v6
await client.FolderMetadata.UpdateFolderMetadataByIdAsync(folderId: folder.Id, scope: UpdateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24 },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }}));
Node v4
await client.folderMetadata.updateFolderMetadataById(
  folder.id,
  'enterprise' as UpdateFolderMetadataByIdScope,
  templateKey,
  [
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/name',
      value: 'Jack',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/age',
      value: 24,
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/birthDate',
      value: '2000-01-03T02:20:50.520Z',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/countryCode',
      value: 'CA',
    } satisfies UpdateFolderMetadataByIdRequestBody,
    {
      op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
      path: '/sports',
      value: ['football'],
    } satisfies UpdateFolderMetadataByIdRequestBody,
  ],
);

認証済みユーザーがファイルのメタデータに対する変更を書き込めるようにするには、ファイルへの書き込みアクセス権限が必要です。

JSON操作

メタデータを更新する場合は、JSON-Patchの仕様に従う必要があります。これは、操作オブジェクトのリストとして表されます。

メタデータインスタンスの場合、これらの操作にはadd、replace、remove、test、move、copyのいずれかを指定できます。どの操作も、opの名前、変更対象のフィールドを指すJSON Pointer pathのほか、実行される操作に応じたvalueまたはfrom値 (省略可) で構成されます。

[
  { "op": "test", "path": "/competitiveDocument", "value": "no" },
  { "op": "remove", "path": "/competitiveDocument" },
  { "op": "test", "path": "/status", "value": "active" },
  { "op": "replace", "path": "/status", "value": "inactive" },
  { "op": "test", "path": "/author", "value": "Jones" },
  { "op": "copy", "from": "/author", "path": "/editor" },
  { "op": "move", "from": "/currentState", "path": "/previousState" },
  { "op": "add", "path": "/currentState", "value": "reviewed" }
]

メタデータを編集する際には、メタデータテンプレートのスキーマに準拠した値のみを使用できます。更新は完全に適用されるか、まったく適用されないかのどちらかです。更新操作の適用中にエラーが発生した場合、メタデータインスタンスは変更されません。

テンプレートインスタンスを更新できるのは、テンプレートがすでにファイルまたはフォルダに割り当てられている場合のみです。

新しい値の追加

テンプレートに新しい値を追加するには、add操作を使用します。

[
  {
    "op": "add",
    "path": "/name",
    "value": "Model 3"
  }
]

これにより、値がModel 3のnameフィールドが追加されます。この操作の前は、テンプレートのnameフィールドに値がありませんでした。

{
  // "name": null, // old value
  "name": "Model 3", // new value
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}

enumおよびmultiSelectフィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。

値の置き換え

テンプレート上の値を置き換えるには、replace操作を使用します。

[
  {
    "op": "replace",
    "path": "/name",
    "value": "Model 4"
  }
]

これにより、nameフィールドの値Model 3が新しい値Model 4に置き換えられます。

{
  // "name": "Model 3", # Old value
  "name": "Model 3", // new value
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}

enumおよびmultiSelectフィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。

値のコピー

値をあるフィールドから別のフィールドにコピーするには、copy操作を使用します。

[
  {
    "op": "copy",
    "from": "/name",
    "path": "/displayName"
  }
]

これにより、nameフィールドの値と一致する値が設定されたdisplayNameフィールドが追加されます。この操作の前は、テンプレートのdisplayNameフィールドに値がありませんでした。

{
  "name": "Model 3",
  "displayName": "Model 3", // new value, copied from the name
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}

enumおよびmultiSelectフィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。

値の移動

値をあるフィールドから別のフィールドに移動するには、move操作を使用します。

[
  {
    "op": "copy",
    "from": "/name",
    "path": "/displayName"
  }
]

これにより、nameフィールドの値と一致する値が設定されたdisplayNameフィールドが追加されます。この操作の前は、テンプレートのdisplayNameフィールドに値がありませんでした。この操作の後、nameフィールドはすでに存在しません。

{
  // "name": "Model 3", // old value, no longer present now
  "displayName": "Model 3", // new value, copied from the name
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}

enumおよびmultiSelectフィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。

値の削除

メタデータインスタンスから値を削除するには、remove操作を使用します。

[
  {
    "op": "remove",
    "path": "/name"
  }
]

これにより、nameフィールドがメタデータインスタンスから完全に削除されます。

{
  // "name": "Model 3", // old value, no longer present now
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}

enumおよびmultiSelectフィールドの場合、この新しい値には、そのフィールドに有効なオプションのいずれかを指定する必要があります。

値のテスト

フィールドに期待する値が設定されていることをテストするには、test操作を使用します。

[
  {
    "op": "test",
    "path": "/name",
    "value": "Model 4"
  }
]

テストに失敗すると、APIはいずれの操作も実行せず、次のエラーとともにHTTPステータス409 Conflictを返します。

{
  "message": "value differs from expectations",
  "code": "failed_json_patch_application",
  "request_id": "bzxgr1gbcq5h67pj"
}

この操作の主な目的は、何らかの操作が実行される前に、メタデータインスタンスの値が予想どおりであることを確認することです。Box APIでは、変更がすべて実行されるかまったく実行されないかのいずれかであるため、テストの失敗は、変換が適用される前にすべての値が予想どおりかどうかを確認するのに非常に役立ちます。