Box Developerドキュメント
ログイン
最新バージョン

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

put
https://api.box.com/2.0
/files/:file_id/metadata/:scope/:template_key

このエンドポイントはバージョン2024.0です。引き続き使用するために 変更は必要ありません。詳細については、 **Box APIのバージョン管理**を参照してください。

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

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

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

関連するガイド

リクエスト

bearer [ACCESS_TOKEN]
application/json-patch+json

パスパラメータ

stringパス内必須
12345

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

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

stringパス内必須
global

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

次の値のいずれか1つ: global,enterprise

stringパス内必須
properties

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

リクエスト本文

object array本文内必須

メタデータインスタンスに変更を加えるためのJSON-Patchの指定。

変更は操作オブジェクトのJSON配列として表されます。

string本文内省略可能
"/nextState"

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

string本文内省略可能
"add"

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

次の値のいずれか1つ: add,replace,remove,test,move,copy

string本文内省略可能
"/currentState"

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

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

string / integer / number (float) / string array 本文内
"reviewed"

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

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

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

レスポンス

application/jsonメタデータインスタンス (Full)

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

application/jsonクライアントエラー

リクエスト本文が無効な場合にエラーを返します。

  • bad_request - リクエスト本文の形式が有効なJSON Patchオブジェクトの配列ではありません。
application/jsonクライアントエラー

リクエスト本文が有効なJSON Patch項目の配列でない場合、一部のエッジケースでエラーを返します。

application/jsonクライアントエラー

予期しないクライアントエラー。

put
ファイルのメタデータインスタンスを更新
このドキュメント内で一部の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"
        }
      ]'
TypeScript Gen
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 Gen
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 Gen
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
BoxFile file = new BoxFile(api, "id");
file.updateMetadata(new Metadata("templateScope", "templateKey").add("/foo", "bar"));
Python
file_obj = client.file(file_id='11111')
file_metadata = file_obj.metadata(scope='enterprise', template='myMetadata')

updates = file_metadata.start_update()
updates.add('/foo', 'bar')
updates.update('/baz', 'murp', old_value='quux')  # Ensure the old value was "quux" before updating to "murp"

updated_metadata = file_metadata.update(updates)
print('Updated metadata on file!')
print(f'foo is now {updated_metadata["foo"]} and baz is now {updated_metadata["baz"]}')
.NET
var updates = new List<BoxMetadataUpdate>()
{
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/competitiveDocument",
        Value = "no"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.remove,
        Path = "/competitiveDocument"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/status",
        Value = "active"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.replace,
        Path = "/competitiveDocument",
        Value = "inactive"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/author",
        Value = "Jones"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.copy,
        From="/author",
        Path = "/editor"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/currentState",
        Value = "proposal"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.move,
        From = "/currentState",
        Path = "/previousState"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.add,
        Path = "/currentState",
        Value = "reviewed"
    }
};
Dictionary<string, object> updatedMetadata = await client.MetadataManager
    .UpdateFileMetadataAsync("11111", updates, "enterprise", "marketingCollateral");
Node
var updates = [
	{ 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.files.updateMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", updates)
	.then(metadata => {
		/* metadata -> {
			audience: 'internal',
			documentType: 'Q1 plans',
			status: 'inactive',
			author: 'Jones',
			'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
			'$parent': 'file_11111',
			'$id': '2094c584-68e1-475c-a581-534a4609594e',
			'$version': 1,
			'$typeVersion': 0,
			editor: 'Jones',
			previousState: 'proposal',
			currentState: 'reviewed',
			'$template': 'marketingCollateral',
			'$scope': 'enterprise_12345' }
		*/
	});

レスポンスの例

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