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

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"],
        ),
    ],
)

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,
  ],
);

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()))

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 = 24L },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"}) }}));

{
  "$parent": "folder_59449484661,",
  "$template": "marketingCollateral",
  "$scope": "enterprise_27335",
  "$version": 1,
  "$canEdit": true,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

メタデータインスタンス (ファイル)

ファイルのメタデータインスタンスを更新

ファイルのメタデータを更新します。

メタデータインスタンスを更新できるのは、テンプレートがすでにファイルに適用されている場合のみです。メタデータを編集する際には、メタデータテンプレートのスキーマに一致した値のみを使用できます。

更新はアトミックに適用されます。操作の適用中にエラーが発生した場合、メタデータインスタンスは変更されません。

PUT

files

{file_id}

metadata

{scope}

{template_key}

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

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"],
        ),
    ],
)

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,
  ],
);

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()))

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 = 24L },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"}) }}));

{
  "$parent": "folder_59449484661,",
  "$template": "marketingCollateral",
  "$scope": "enterprise_27335",
  "$version": 1,
  "$canEdit": true,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "message": "Method Not Allowed",
  "context_info": {
    "message": "Something went wrong"
  },
  "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
  "request_id": "abcdef123456"
}

このリソースは、バージョン2024.0のエンドポイントで使用されています。詳細については、 Box APIのバージョン管理を参照してください。「Box SDKのバージョニング戦略について詳しく学ぶ。」

承認

Authorization

string

header

必須

The access token received from the authorization server in the OAuth 2.0 flow.

パスパラメータ

file_id

string

必須

ファイルを表す一意の識別子。

ファイルIDを確認するには、ウェブアプリケーションでファイルにアクセスして、URLからIDをコピーします。たとえば、URLがhttps://*.app.box.com/files/123の場合、file_idは123です。

scope

enum<string>

必須

メタデータテンプレートのスコープ。

利用可能なオプション:

global,

enterprise

template_key

string

必須

メタデータテンプレートの名前。

ボディ

application/json-patch+json

enum<string>

テンプレートに対して実行する変更のタイプ。その中には、既存のテンプレートを変更する際に危険を伴うものもあります。

利用可能なオプション:

add,

replace,

remove,

test,

move,

copy

例:

"add"

path

string

変更を適用するメタデータJSONオブジェクト内の場所を、JSON-Pointerの形式で指定します。

パスの先頭にはテンプレートのルートを表す/を必ず付ける必要があります。文字~と/は予約文字であるため、キー内ではエスケープする必要があります。

例:

"/currentState"

value

設定またはテストする値。

add、replace、test操作では必須です。addの場合、値がすでに存在するときは、古い値が新しい値で上書きされます。replaceの場合、置換の前に値がすでに存在している必要があります。

testの場合、pathの位置にある既存の値が指定した値と一致している必要があります。

例:

"reviewed"

from

string

値の移動元またはコピー元であるメタデータJSONオブジェクト内の場所。moveまたはcopy操作には必須であり、JSON-Pointerの形式である必要があります。

例:

"/nextState"

レスポンス

カスタムテンプレートデータを含め、更新されたメタデータテンプレートインスタンスを返します。

ファイルまたはフォルダに適用された、メタデータテンプレートのインスタンス。

$parent

string

このメタデータインスタンスが追加されている項目の識別子。これは、親のtypeとidを{type}_{id}という形式で組み合わせたものです。

例:

"folder_59449484661,"

$template

string

テンプレートの名前。

例:

"marketingCollateral"

$scope

string

このテンプレートが適用されているスコープのID。これは、この会社で使用するために定義されたテンプレートの場合はenterprise_{enterprise_id}、Boxを使用するすべての会社が利用できる一般的なテンプレートの場合はglobalになります。

例:

"enterprise_27335"

$version

integer

メタデータインスタンスのバージョン。このバージョンは0から始まり、ユーザー定義プロパティが変更されるたびに増加します。

例:

1

$canEdit

boolean

このメタデータインスタンスをユーザーが編集できるかどうか。

例:

true

$id

string<uuid>

メタデータインスタンスを識別するためのUUID。

Maximum string length: 36

例:

"01234500-12f1-1234-aa12-b1d234cb567e"

$type

string

このインスタンスの「タイプ」に対応する一意の識別子。これは内部システムプロパティであるため、クライアントアプリケーションでは使用しないでください。

例:

"properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0"

$typeVersion

integer

オブジェクトテンプレートの既知の最新バージョン。これは内部システムプロパティであるため、クライアントアプリケーションでは使用しないでください。

例:

2

{key}

any

メタデータテンプレートに存在する各フィールドの値。global.propertiesテンプレートの場合、汎用的なキー/値ペアをテンプレートに保存できるため、0個以上のフィールドのリストにすることができます。

例:

"Aaron Levie"

最終更新日 2026年1月23日

v2025.0

v2026.0

ファイルのメタデータインスタンスを更新

承認

パスパラメータ

ボディ

レスポンス