IPWorks Cloud 2020 PHP Edition

Questions / Feedback?

UpdateMetadata Method

Updates the metadata items for an existing metadata container.

Object Oriented Interface

public function doUpdateMetadata($resourceid, $scope, $schema);

Procedural Interface

ipworkscloud_box_do_updatemetadata($res, $resourceid, $scope, $schema);

Remarks

This method updates the metadata items for an existing metadata container, specified by Scope and Schema, that is associated with the resource specified by ResourceId.

Scope must be global or an enterprise-specific scope of the form enterprise_<EnterpriseId>. If Scope is empty, global is used.

If Scope is global, then Schema must be properties; otherwise, it must be the name of an existing metadata container schema owned by the enterprise identified in Scope. If Schema is empty, properties is used.

Each item represented by the Metadata* properties has a MetadataModOp property which can be set to one of the following values:

0 (opNone - default) No-Op (the class skips the metadata item).
1 (opAdd) A new metadata item will be added. If one already exists with the specified MetadataName, its value will be overwritten.
2 (opReplace) The metadata item with the given MetadataName (which must already exist) will have its value overwritten.
3 (opCopyFrom) A new metadata item will be added, its value copied from the item specified by MetadataSourceName (which must already exist).
4 (opMoveFrom) A new metadata item will be added, its value moved from the item specified by MetadataSourceName (which must already exist). The source item will then be removed.
5 (opRemove) The metadata item with the given MetadataName (which must already exist) will be removed.
6 (opTest) Will verify that the metadata item with the given MetadataName (which must already exist) has the specified MetadataValue.

When this method is called, the class will iterate through the Metadata* properties and build up a modification request that includes the specified operation for each applicable metadata item. For a metadata item to be included in the request, all of the following must be true:

A couple of things to keep in mind regarding metadata item modification operations:

  • Box applies each modification operation in the request sequentially, so the order in which they are transmitted is significant (though it may not impact all use-cases).
    • By default, the class transmits the applicable modification operations based on the order of the Metadata* items.
    • To specify an explicit order, the MetadataUpdateOrder configuration setting can be set to a comma-separated list of Metadata* item indices.
  • Box guarantees overall atomicity for the request; if the modification operation for any one item fails, then the whole request fails, and no changes are made.
  • If the request completes successfully, the class will reset all affected metadata items' MetadataModOp properties back to 0 (opNone).

Usage

ListMetadata must be called before using this method in order to populate the Metadata* properties with a resource's existing metadata items. (When creating new metadata items, calling ListMetadata first is optional, but still recommended to ensure that the class reflects the latest information.)

To create new metadata items, add new items to the Metadata* properties by incrementing the MetadataCount property as necessary.

For each metadata item being created or updated, set its properties to the desired values. The MetadataModOp property should be set to a value other than 0 (opNone).

Once the metadata items have been set up as desired, call this method.

Metadata Notes

Box's Metadata architecture consists of two entities: metadata items, and metadata containers (which Box calls "metadata templates").

A metadata item is just a name-value pair held by a metadata container. Its name may be up to 256 characters long, cannot begin with the $ character, and must be unique within the container.

A metadata container holds metadata items, and is associated with a single resource. All metadata containers must be created using a metadata container schema, which describes the possible metadata items the container may hold. Containers are uniquely identified (per-resource) by a schema path like /Scope/Schema (ergo, a resource cannot have multiple containers of the same schema).

Box provides a general-use schema, /global/properties, that functions as an unrestricted key-value store that will accept any metadata item. Enterprises can also create custom schemas, /enterprise_<EnterpriseId>/Schema, that only allow predefined metadata items (with specific data types) to be added.

See the following methods for more information: CreateMetadata, ListMetadata, UpdateMetadata, and DeleteMetadata.

Note that metadata is only usable on resources owned by paid Box accounts.

string resId = "f:09876";

// Create an instance of the default metadata container ("/global/properties") with a couple of metadata 
// items in it, and associate it with the specified resource. (Note that we're assuming that the given
// resource doesn't already have an instance of the default metadata container associated with it.)
box.Metadata.Add(new BoxMetadata() { Name = "num1", Value = "123", ModOp = BoxMetadataModOps.opAdd });
box.Metadata.Add(new BoxMetadata() { Name = "text1", Value = "abc", ModOp = BoxMetadataModOps.opAdd });

// All of the class's metadata-related methods all empty string to be passed to their Scope and Schema
// parameters, in which case "global" and "properties" will be used, respectively. (The exception is the
// ListMetadata() method, which interprets empty Scope and Schema values in a different way; refer to the
// ListMetadata() documentation for more information.)
box.CreateMetadata(resId, "", "");

// Some time later, imagine you wish to update the metadata items held by the default container on that
// resource. Always call ListMetadata() first so that class has the latest metadata loaded.
box.ListMetadata(resId, "global", "properties");

// Now that the class has the latest metadata items loaded for the default container on the given
// resource, we can modify what we wish to, setting the ModOp fields appropriately.
box.Metadata[0].Value = "456"; // Update the value of the "num1" item.
box.Metadata[0].ModOp = BoxMetadataModOps.opReplace;
box.Metadata[1].ModOp = BoxMetadataModOps.opRemove; // Remove the "text1" item.
// Add a new "text2" item.
box.Metadata.Add(new BoxMetadata() { Name = "text2", Value = "def", ModOp = BoxMetadataModOps.opAdd });

// Now commit the updates. Our example performs very simple updates, but you can build a very complex
// update scenario using some of the other ModOp values. Refer to the UpdateMetadata() documentation
// for more information.
box.UpdateMetadata(resId, "", "");

// Finally, this will remove the entire default metadata container from the given resource.
box.DeleteMetadata(resId, "", "");

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks Cloud 2020 PHP Edition - Version 20.0 [Build 8265]