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

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

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

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

ファイルにメタデータを適用

メタデータテンプレートのインスタンスをファイルに適用するには、ファイルのfile_id、テンプレートのscopetemplateKey、および必要に応じてテンプレート内の各フィールドの値のセットを指定して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"
     }'
.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");
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('Applied metadata in instance ID {0}'.format(applied_metadata['$id']))
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' }
		*/
	});
iOS
let metadata = [
    "name": "John Doe",
    "birthday": "2000-01-01T00:00:00Z",
    "department": "Sales"
]
client.metadata.create(
    forFileWithId: "11111",
    scope: "enterprise",
    templateKey: "personnelRecord",
    keys: metadata
) { (result: Result<MetadataObject, BoxSDKError>) in
    guard case let .success(metadata) = result {
        print("Error adding metadata")
        return
    }

    print("Successfully attached metadata")
}

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

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

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

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

メタデータテンプレートのインスタンスをフォルダに適用するには、フォルダのfolder_id、テンプレートのscopetemplateKey、および必要に応じてテンプレート内の各フィールドの値のセットを指定して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"
     }'
.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");
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('Applied metadata in instance ID {0}'.format(applied_metadata['$id']))
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' }
		*/
	});
iOS
let metadata = [
    "name": "John Doe",
    "birthday": "2000-01-01T00:00:00Z",
    "department": "Sales"
]
client.metadata.create(
    forFolderWithId: "22222",
    scope: "enterprise",
    templateKey: "personnelRecord",
    keys: metadata
) { (result: Result<MetadataObject, BoxSDKError>) in
    guard case let .success(metadata) = result {
        print("Error adding metadata")
        return
    }

    print("Successfully attached metadata")
}

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

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

指定されたメタデータテンプレートでこのフォルダにすでにメタデータが適用されている場合、エラーコード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つのテンプレートフィールドとしてnamecategoryがあります。nameフィールドは通常のテキストフィールドで、categoryは列挙型フィールドです。

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

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

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

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

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