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

put

https://api.box.com/2.0

/files/:file_id/metadata/:scope/:template_key

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

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

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

関連するガイド

メタデータ項目のメタデータの更新

リクエスト

authorizationbearer [ACCESS_TOKEN]

content-typeapplication/json-patch+json

パスパラメータ

file_id stringパス内必須

例12345

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

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

scope stringパス内必須

例global

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

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

template_key stringパス内必須

例properties

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

リクエスト本文

<item> object array本文内必須

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

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

[<item>].from string本文内省略可能

例"/nextState"

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

[<item>].op string本文内省略可能

例"add"

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

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

[<item>].path string本文内省略可能

例"/currentState"

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

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

[<item>].value string本文内省略可能

例"reviewed"

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

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

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

レスポンス

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

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

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

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

bad_request - リクエスト本文の形式が有効なJSON Patchオブジェクトの配列ではありません。

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

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

defaultapplication/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,
  'global' as UpdateFileMetadataByIdScope,
  'properties',
  [
    {
      op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
      path: '/abc',
      value: newValue,
    } satisfies UpdateFileMetadataByIdRequestBody,
  ],
);

Python Gen

client.file_metadata.update_file_metadata_by_id(
    file.id,
    UpdateFileMetadataByIdScope.GLOBAL.value,
    "properties",
    [
        UpdateFileMetadataByIdRequestBody(
            op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE.value,
            path="/abc",
            value=new_value,
        )
    ],
)

.NET Gen

await client.FileMetadata.UpdateFileMetadataByIdAsync(fileId: file.Id, scope: UpdateFileMetadataByIdScope.Global, templateKey: "properties", requestBody: Array.AsReadOnly(new [] {new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/abc", Value = newValue }}));

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' }
		*/
	});

iOS

client.metadata.update(
    forFileWithId: "11111",
    scope: "enterprise",
    templateKey: "personnelRecord",
    operations: [
        .test(path: "/department", value: "Sales"),
        .replace(path: "/department", value: "Marketing")
    ]
) { (result: Result<MetadataObject, BoxSDKError>) in
    guard case let .success(metadata) = result {
        print("Error updating metadata")
        return
    }

    print("Employee department updated to \(metadata.keys["department"])")
}

レスポンスの例

{
  "$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
}