項目へのメタデータの適用

必須のガイド

ガイドすべてのメタデータテンプレートのリストの取得

項目へのメタデータの適用

メタデータテンプレートは、項目のid、テンプレートのtemplateKeyとscope、およびテンプレート内の各フィールドの値のセットを使用してファイルまたはフォルダに適用できます。

メタデータのスコープには、global (すべての会社が利用できるテンプレートの場合)、enterprise (現在の会社が利用できるテンプレートの場合)、またはenterprise_:id (IDがスコープ名の:idである会社に属するテンプレートの場合) のいずれかを指定できます。

特定のファイルまたはフォルダには最大100個のテンプレートを割り当てることができます。

メタデータテンプレートのインスタンスをファイルに適用するには、ファイルのfile_id、テンプレートのscopeとtemplateKey、および必要に応じてテンプレート内の各フィールドの値のセットを指定してPOST /files/:file_id/metadata/:scope/:templateKey APIエンドポイントを呼び出します。

cURL

curl -i -X POST "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "audience": "internal",
       "documentType": "Q1 plans",
       "competitiveDocument": "no",
       "status": "active",
       "author": "Jones",
       "currentState": "proposal"
     }'

TypeScript Gen

await client.fileMetadata.createFileMetadataById(
  file.id,
  'enterprise' as CreateFileMetadataByIdScope,
  templateKey,
  {
    ['name']: 'John',
    ['age']: 23,
    ['birthDate']: '2001-01-03T02:20:50.520Z',
    ['countryCode']: 'US',
    ['sports']: ['basketball', 'tennis'],
  },
);

Python Gen

client.file_metadata.create_file_metadata_by_id(
    file.id,
    CreateFileMetadataByIdScope.ENTERPRISE,
    template_key,
    {
        "name": "John",
        "age": 23,
        "birthDate": "2001-01-03T02:20:50.520Z",
        "countryCode": "US",
        "sports": ["basketball", "tennis"],
    },
)

.NET Gen

await client.FileMetadata.CreateFileMetadataByIdAsync(fileId: file.Id, scope: CreateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary<string, object>() { { "name", "John" }, { "age", 23 }, { "birthDate", "2001-01-03T02:20:50.520Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } });

Java

// Add property "foo" with value "bar" to the default metadata properties
BoxFile file = new BoxFile(api, "id");
file.createMetadata(new Metadata().add("/foo", "bar"));

Python

metadata = {
    'foo': 'bar',
    'baz': 'quux',
}

applied_metadata = client.file(file_id='11111').metadata().create(metadata)
print(f'Applied metadata in instance ID {applied_metadata["$id"]}')

.NET

var metadataValues = new Dictionary<string, object>()
{
    { "audience", "internal" },
    { "documentType", "Q1 plans" },
    { "competitiveDocument", "no" },
    { "status", "active" },
    { "author": "M. Jones" },
    { "currentState": "proposal" }
};
Dictionary<string, object> metadata = await client.MetadataManager
    .CreateFileMetadataAsync(fileId: "11111", metadataValues, "enterprise", "marketingCollateral");

Node

var metadataValues = {
	audience: "internal",
	documentType: "Q1 plans",
	competitiveDocument: "no",
	status: "active",
	author: "Jones",
	currentState: "proposal"
};
client.files.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues)
	.then(metadata => {
		/* metadata -> {
			audience: 'internal',
			documentType: 'Q1 plans',
			competitiveDocument: 'no',
			status: 'active',
			author: 'Jones',
			currentState: 'proposal',
			'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
			'$parent': 'file_11111',
			'$id': '2094c584-68e1-475c-a581-534a4609594e',
			'$version': 0,
			'$typeVersion': 0,
			'$template': 'marketingCollateral',
			'$scope': 'enterprise_12345' }
		*/
	});

テンプレートのscopeとtemplateKeyを取得するには、すべてのメタデータテンプレートのリストを取得するか、ファイルのすべてのインスタンスのリストを取得します。

指定されたメタデータテンプレートでこのファイルにすでにメタデータが適用されている場合、エラーコードtuple_already_existsでエラーが返されます。この場合は、インスタンスを代わりに更新する必要があります。

メタデータテンプレートのインスタンスをフォルダに適用するには、フォルダのfolder_id、テンプレートのscopeとtemplateKey、および必要に応じてテンプレート内の各フィールドの値のセットを指定してPOST /folders/:folder_id/metadata/:scope/:templateKey APIエンドポイントを呼び出します。

cURL

curl -i -X POST "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "audience": "internal",
       "documentType": "Q1 plans",
       "competitiveDocument": "no",
       "status": "active",
       "author": "Jones",
       "currentState": "proposal"
     }'

TypeScript Gen

await client.folderMetadata.createFolderMetadataById(
  folder.id,
  'enterprise' as CreateFolderMetadataByIdScope,
  templateKey,
  {
    ['name']: 'John',
    ['age']: 23,
    ['birthDate']: '2001-01-03T02:20:50.520Z',
    ['countryCode']: 'US',
    ['sports']: ['basketball', 'tennis'],
  },
);

Python Gen

client.folder_metadata.create_folder_metadata_by_id(
    folder.id,
    CreateFolderMetadataByIdScope.ENTERPRISE,
    template_key,
    {
        "name": "John",
        "age": 23,
        "birthDate": "2001-01-03T02:20:50.520Z",
        "countryCode": "US",
        "sports": ["basketball", "tennis"],
    },
)

.NET Gen

await client.FolderMetadata.CreateFolderMetadataByIdAsync(folderId: folder.Id, scope: CreateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary<string, object>() { { "name", "John" }, { "age", 23 }, { "birthDate", "2001-01-03T02:20:50.520Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } });

Java

BoxFolder folder = new BoxFolder(api, "id");
folder.createMetadata(new Metadata().add("/foo", "bar"));

Python

metadata = {
    'foo': 'bar',
    'baz': 'quux',
}

applied_metadata = client.folder(folder_id='22222').metadata().create(metadata)
print(f'Applied metadata in instance ID {applied_metadata["$id"]}')

.NET

var metadataValues = new Dictionary<string, object>()
{
    { "audience", "internal" },
    { "documentType", "Q1 plans" },
    { "competitiveDocument", "no" },
    { "status", "active" },
    { "author": "M. Jones" },
    { "currentState": "proposal" }
};
Dictionary<string, object> metadata = await client.MetadataManager
    .CreateFolderMetadataAsync(folderId: "11111", metadataValues, "enterprise", "marketingCollateral");

Node

var metadataValues = {
	audience: "internal",
	documentType: "Q1 plans",
	competitiveDocument: "no",
	status: "active",
	author: "Jones",
	currentState: "proposal"
};
client.folders.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues)
	.then(metadata => {
		/* metadata -> {
			audience: 'internal',
			documentType: 'Q1 plans',
			competitiveDocument: 'no',
			status: 'active',
			author: 'Jones',
			currentState: 'proposal',
			'$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
			'$parent': 'folder_11111',
			'$id': '2094c584-68e1-475c-a581-534a4609594e',
			'$version': 0,
			'$typeVersion': 0,
			'$template': 'marketingCollateral',
			'$scope': 'enterprise_12345' }
		*/
	});

テンプレートのscopeとtemplateKeyを取得するには、すべてのメタデータテンプレートのリストを取得するか、フォルダのすべてのインスタンスのリストを取得します。

指定されたメタデータテンプレートでこのフォルダにすでにメタデータが適用されている場合、エラーコードtuple_already_existsでエラーが返されます。この場合は、インスタンスを代わりに更新する必要があります。

リクエストの本文には、テンプレート内の各フィールドの値を含めることができます。テンプレートに存在するフィールドを調べるには、メタデータテンプレートを調査してください。

たとえば、次のテンプレートについて考えましょう。

{
  "id": "8120731a-41e4-11ea-b77f-2e728ce88125",
  "type": "metadata_template",
  "templateKey": "productInfo",
  "scope": "enterprise_1234567",
  "displayName": "Product Info",
  "hidden": false,
  "copyInstanceOnItemCopy": true,
  "fields": [
    {
      "id": "feed71de-41e5-11ea-b77f-2e728ce88125",
      "type": "string",
      "key": "name",
      "displayName": "Name",
      "hidden": false
    },
    {
      "id": "02b36bb6-41e6-11ea-b77f-2e728ce88125",
      "type": "enum",
      "key": "category",
      "displayName": "Category",
      "hidden": false,
      "options": [
        {
          "id": "06a7bcc2-41e6-11ea-b77f-2e728ce88125",
          "key": "SUVs"
        },
        {
          "id": "0a50df02-41e6-11ea-b77f-2e728ce88125",
          "key": "Saloons"
        },
        {
          "id": "0e466be0-41e6-11ea-b77f-2e728ce88125",
          "key": "Cabriolets"
        }
      ]
    }
  ]
}

このテンプレートには、2つのテンプレートフィールドとしてnameとcategoryがあります。nameフィールドは通常のテキストフィールドで、categoryは列挙型フィールドです。

このテンプレートをファイルまたはフォルダに割り当てるリクエストの本文には、テンプレートの任意のフィールドの値を含めることができます。本文にフィールドも値も含めないことも可能です。

この場合、次のリクエスト本文は有効な例です。

{
  "name": "Model 3",
  "category": "SUVs"
}

キーpropertiesを使用してスコープがglobalに設定されたテンプレートは例外で、テンプレートに任意のデータを割り当てることができます。このテンプレートを使用すると、一連のキー/値ペアをテンプレートに割り当てることができます。

この例のcategoryフィールドはenumフィールドで、このフィールドで使用できるオプションのいずれかを指定する必要があります。

項目へのメタデータの適用

必須のガイド

項目へのメタデータの適用

ファイルへのメタデータの適用

タプルがすでに存在することを示すエラー

フォルダにメタデータを適用

タプルがすでに存在することを示すエラー

リクエスト本文

関連するAPI

関連するガイド