Skip to main content
English (United States) Nederlands

Assets Server REST API - updatebulk

Updated

What does it do?

This call updates the metadata of multiple existing assets in Assets Server, either by using a query or based on ID.

Log in requirement

Before being able to request information from Assets Server by using a GET request or make changes to the system through a POST request, a log in to Assets Server is required. For information about the available APIs for logging in, see Assets Server REST API - introduction.

POST requests only

This REST API only accepts POST requests, not GET requests. Also, the POST request needs to include a cross-site request forgery (csrf) token.

The csrf token is a unique code which, by including it in the request, also makes the POST request unique and therefore much more secure.

The csrf token is obtained by first logging in to Assets Server through a POST request. The response that is received will include the csrf token which can then be used in subsequent POST requests as a http header:

"X-CSRF-TOKEN: <some_csrf_token>"

For more information including examples, see Assets Server REST API - Performing a POST request with a csrf token.

Methods

Metadata can be updated either based on ID or by using a query.

Based on ID

In this method, assets are targeted by referencing their ID.

The API endpoint is the same as for the query method, but it takes an array of objects as parameter:

[object1, object2,object3,...]

The object in the array should have an "id" of type 'string' and a metadata object. For example:

[
  {
    "id":"8LYE_winarE8ETOFU9L2di",
    "metadata":{
      "status":"Draft"
    }
  },
  {
    "id":"8vUY-5NlKR_9d4URK-YfpP",
    "metadata":{
      "status":"Production",
      "description":"Ready for production"
    }
  },
  {
    "id":"Dnt5MAmPqVo9R1jZXpOpGN",
    "metadata":{
      "description":"A nice description of my file"
    }
  }
]

An array is returned with the updated asset objects, similar to the given parameters.

Using a query

In this method, assets are targeted based on a general query.

POST 

http://yourserver.com/services/updatebulk
    ?q=<query>
    &metadata=<JSON encoded metadata>
    &<Elvis metadata field name>=<value>

Parameters

q

A query matching the assets that should be updated, see the query syntax guide for details.

Required.

Note: Since you use a query to specify which assets to update, make sure you use the right query, or you might end updating the wrong assets or a huge amounts of them. The process runs on the server, so the amount of assets is no problem, but it may take quite some time. You can see the status of all bulk processes on the server status page.

Updating metadata that is not embedded is usually very fast, we typically see rates of several thousands per minute. If metadata needs to be embedded however, it has to alter the files on disk and speed will depend on factors like file size and disk speed. If your server gets slow because of too many concurrently running embeds, consider configuring a lower processing capacity for the main server.
metadata

A JSON encoded object with properties that match Assets Server metadata field names. This metadata will be set on the asset in Assets Server.

Optional. You can also use parameters matching Assets Server field names.
*

Any parameter matching an Assets Server metadata field name will be used as metadata. This metadata will be set on the asset in Assets Server.

Optional. You also use the 'metadata' parameter.

Tip: The update bulk service uses the same kind of parameters to specify metadata as the update service.
async

When true, the process will run asynchronous in the background. The call will return immediate with the processId.

Optional. By default, the call waits for the process to finish and then returns the processedCount.
parseMetadataModifications

Prevents parsing "+" and "-" when set to false.

Optional. Default true.

Return value

The operation returns a JSON object with the following properties:

processedCount Number of assets that were processed by the operation.
errorCount Number of errors that occurred.

If called with async=true, the operation returns a JSON object with the following properties:

processId Unique id of the process that was started.

If the operation fails, a JSON error object is returned.

Examples

Update metadata

This call sets the rating to 4 and status to New for all assets with the tag "animal":

update 

http://demo.assets-server.com/services/updatebulk
    ?q=tags:animal
    &metadata={rating: -1, status: "Correction"}

Passing metadata as separate parameters is useful when working with HTML forms, but for AJAX calls it can be easier to pass metadata as a JSON encoded string. The following will set the rating to "Rejected" (-1) and will change the status to "Correction" on all assets below the "Demo Zone/Images/Nature" folder:

update
http://demo.assets-server.com/services/updatebulk
    ?q=ancestorPaths:"/Demo Zone/Images/Nature"
    &rating=0
    &status=New

Add values to existing metadata

Using an updatebulk, you can append or remove existing metadata on multiple assets. For example, you could add a tag to a set of assets while leaving their current tags intact.

Tip: You need to escape the '+' character with %2B if you use it in URLs. A plain '+' would be interpreted as a space character (as defined in the specification on URL encoding).

The following call will remove the "house" tag from all assets that have it, while at the same time adding the tags "beach", "villa", "sunny". If one of the assets has the tags "sea", "bay", those would not be removed. If one of the assets has the tag "villa", it will not get "villa" twice; assets can only have a specific tag once.

update
http://demo.assets-server.com/services/updatebulk
    ?q=tags:house
    &tags=%2Bbeach, -house, %2Bvilla, %2Bsunny

It is also possible to append text to a single value field using the '+' character or add text around the existing value using {CURRENT}.

update 

http://demo.assets-server.com/services/updatebulk
    ?q=tags:house
    &description=%2Bhouse
    &subject=before{CURRENT}after

Related articles

Comments

0 comments