The Metadata API enables applications to:
Terminology:
Setting up our client, we want to subclass the DefaultNetwork to add illustrative logging to our output:
from boxsdk.network.default_network import DefaultNetwork
from pprint import pformat
class LoggingNetwork(DefaultNetwork):
def request(self, method, url, access_token, **kwargs):
print '\x1b[36m{} {} {}\x1b[0m'.format(method, url, pformat(kwargs))
response = super(LoggingNetwork, self).request(
method, url, access_token, **kwargs
)
if response.ok:
print '\x1b[32m{}\x1b[0m'.format(response.content)
else:
print '\x1b[31m{}\n{}\n{}\x1b[0m'.format(
response.status_code,
response.headers,
pformat(response.content),
)
return response
Fill in your client_id, client_secret, and developer token that you obtained from the developers site:
from boxsdk import OAuth2
from boxsdk import Client
oauth = OAuth2(client_id='YOUR_CLIENT_ID', client_secret='YOUR_CLIENT_SECRET', access_token='YOUR_DEVELOPER_TOKEN')
client = Client(oauth, LoggingNetwork())
I'll demonstrate the CRUD abilities of the Metadata API. Using the Python SDK makes the API dead simple to use.
First, let's assume our account already has a file with ID 28792944858 and a template named "mortgageContarct". We'll create a metadata instance of that type:
metadata = client.file(28792944858).metadata('enterprise', 'mortgageApplication')
metadata.create({'borrowerName':'Alice', 'amount':8888888, 'status':'Pending Approval'})
The metadata instance has been created and returned to you.
Next, we'll demonstrate the Metadata Search API. The Metadata Search API allows clients to search for files that match certain metadata values.
For example, our user's enterprise has a Mortgage Application metadata template, and we've attached an instance of the Mortgage Application template to a file in the user's account. We can search for this file by a specific field, status. In this example, the template is identified by template_key and scope, and the value itself is identified by the field_key.
from boxsdk.object.search import Search
metadata_filters = Search.start_metadata_filters()
metadata_filter = Search.make_single_metadata_filter(template_key='mortgageApplication', scope='enterprise')
metadata_filter.add_value_based_filter(field_key='status', value='Pending Approval')
metadata_filters.add_filter(metadata_filter)
client.search('pdf', limit=1, offset=0, metadata_filters=metadata_filters)
Next, we'll update the metadata instance, testing that the value is still what we expect it to be:
from boxsdk.object.metadata import Metadata
update = Metadata.start_update()
update.update('/status', 'Approved', 'Pending Approval')
metadata.update(update)
Notice the PUT body is an array of 2 operations: test and replace. The PUT body conforms to the JSON Patch specification for updating JSON objects.
If we attempt to issue the same patch again, the operation will fail because the value is not what we expected it to be:
update = Metadata.start_update()
update.update('/status', 'Approved', 'Pending Approval')
metadata.update(update)
Now, we'll retrieve the metadata again to demonstrate the GET operation:
metadata.get()
Finally, we'll delete the metadata on the file:
metadata.delete()
If we attempt to retrieve the metadata again, then the metadata will not be found:
metadata.get()
That's it! Now you'll be able to easily CRUD metadata and search for files with metadata using the Python SDK.
This notebook is available for download: http://opensource.box.com/box-python-sdk/tutorials/metadata.ipynb
Its content is licensed under the Apache License 2.0.
To reproduce the presentation, execute the following commands:
curl -O http://opensource.box.com/box-python-sdk/tutorials/metadata.ipynb
pip install boxsdk ipython[notebook]
ipython notebook metadata.ipynb