# omeka = OmekaAPIClient('http://timsherratt.org/collections/api')
= OmekaAPIClient(os.getenv('API_URL'), use_cache=False) omeka
Omeka S API client
OmekaAPIClient
OmekaAPIClient (api_url, key_identity=None, key_credential=None, use_cache=True)
Initialize self. See help(type(self)) for accurate signature.
First import the OmekaAPIClient
class.
from omeka_s_tools.api import OmekaAPIClient
To initialise the OmekaAPIClient
you need to provide the base url of your Omeka instance’s API.
This will let you access details of all public resources provided by your Omeka instance. To access private resources, or create new resources, you’ll have to authenticate your API requests by provide a key_identity
and key_credential
. See Adding items for an example.
Getting resources
You can find a full list of Omeka’s resources in the API documentation. You’re most likely to be interested in ‘items’, but accessing ‘properties’ and ‘resource_templates’ can be useful when you’re creating new resources.
You should be able to use get_resources
with any of the resource types, though some of the parameters will be different.
OmekaAPIClient.get_resources
OmekaAPIClient.get_resources (resource_type, **kwargs)
Get a list of resources matching the supplied parameters.
This will return the first page of matching results. To retrieve additional pages, you can supply the page
parameter to move through the full result set.
Parameters:
* resource_type
- one of Omeka’s resource types, eg: ‘items’, ‘properties’
* there are many additional parameters you can supply as kwargs, see the Omeka documention
Returns a dict with the following values:
* total_results
- number of matching resources
* results
- a list of dicts, each containing a JSON-LD formatted representation of a resource
= omeka.get_resources('items')
data 'total_results'] data[
7109
assert isinstance(data['total_results'], int)
# Get a list of available resource templates
= omeka.get_resources('resource_templates')
data = data['results'][0]
first_template assert first_template['@type'] == 'o:ResourceTemplate'
OmekaAPIClient.get_resource_by_id
OmekaAPIClient.get_resource_by_id (resource_id, resource_type='items')
Get a resource from its Omeka id.
Parameters:
* resource_id
- numeric identifier used by Omeka for this resource
* resource_type
- one of Omeka’s resource types, eg: ‘items’, ‘properties’
Returns
* a dict containing a JSON-LD formatted representation of the resource
# Get a random item from a list of items
= omeka.get_resources('items')
data = random.choice(data['results'])
random_item = random_item['o:id']
item_id
# Get the same item using its id
= omeka.get_resource_by_id(item_id, 'items')
item_from_id
# Check that they're the same
assert random_item == item_from_id
It can be difficult to remember all the available parameters and the differences between resource types, so I’ve created a number of more specialised methods that are really just wrappers around get_resources
.
OmekaAPIClient.get_template_by_label
OmekaAPIClient.get_template_by_label (label)
Get a resource template from its Omeka label.
Parameters:
* label
- the name of the resource template in Omeka (eg. ‘NewspaperArticle’)
Returns:
* dict containing representation of the template
= omeka.get_template_by_label('Newspaper')
newspaper_template
assert newspaper_template['@type'] == 'o:ResourceTemplate'
assert newspaper_template['o:label'] == 'Newspaper'
# Get a random template from list
= random.choice(omeka.get_resources('resource_templates')['results'])
template_from_list = template_from_list['o:label']
label
# Get the template using label
= omeka.get_template_by_label(label)
template_from_label
# Check they're both the same
assert template_from_list == template_from_label
OmekaAPIClient.get_resource_by_term
OmekaAPIClient.get_resource_by_term (term, resource_type='properties')
Get the resource (property or class) associated with the suppied term.
Parameters:
* term
- property label qualified with vocabulary prefix (eg: ‘schema:name’)
Returns:
* dict containing representation of the resource
= omeka.get_resource_by_term('schema:name')
prop prop
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/properties/2922',
'@type': 'o:Property',
'o:id': 2922,
'o:local_name': 'name',
'o:label': 'name',
'o:comment': 'The name of the item.',
'o:term': 'schema:name',
'o:vocabulary': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/vocabularies/7',
'o:id': 7}}
assert prop['@type'] == 'o:Property'
assert prop['o:term'] == 'schema:name'
OmekaAPIClient.get_resource_from_vocab
OmekaAPIClient.get_resource_from_vocab (local_name, vocabulary_namespace_uri='http:// schema.org/', resource_type='properties')
Get the resource (property or class) associated with the suppied vocabulary and label.
Parameters:
* local_name
- label of the property or class
* vocabulary_namespace_uri
- URI defining the vocab
Returns:
* dict containing representation of the resource
= omeka.get_resource_from_vocab(
prop 'name',
='http://schema.org/',
vocabulary_namespace_uri='properties')
resource_type prop
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/properties/2922',
'@type': 'o:Property',
'o:id': 2922,
'o:local_name': 'name',
'o:label': 'name',
'o:comment': 'The name of the item.',
'o:term': 'schema:name',
'o:vocabulary': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/vocabularies/7',
'o:id': 7}}
= requests.get(prop['o:vocabulary']['@id'])
vocab = vocab.json()['o:namespace_uri']
namespace_uri
assert namespace_uri == 'http://schema.org/'
assert prop['o:local_name'] == 'name'
OmekaAPIClient.get_property_id
OmekaAPIClient.get_property_id (term)
Get the numeric identifier associated with the supplied property term.
Parameters:
* term
- property label qualified with vocabulary prefix (eg: ‘schema:name’)
Returns:
* numeric identifier
= omeka.get_property_id('schema:name')
prop_id prop_id
2922
assert isinstance(prop_id, int)
= omeka.get_resource_by_id(prop_id, 'properties')
prop assert prop['o:term'] == 'schema:name'
OmekaAPIClient.filter_items_by_property
OmekaAPIClient.filter_items_by_property (filter_property='schema:name', filter_value='', filter_type='eq', page=1, **extra_filters)
Filter the list of items by searching for a value in a particular property.
Additional filters can also limit to items associated with particular templates, classes, or item sets.
Parameters:
* filter_property
- property term (eg: ‘schema:name’)
* filter_value
- the value you want to find
* filter_type
- how filter_value
should be compared to the stored values (eg: ‘eq’)
* page
- number of results page
Additional parameters:
* resource_template_id
- numeric identifier
* resource_class_id
- numeric identifier
* item_set_id
- numeric identifier
* is_public
- boolean, True or False
Returns a dict with the following values:
* total_results
- number of matching resources
* results
- a list of dicts, each containing a JSON-LD formatted representation of a resource
= omeka.filter_items_by_property(filter_property='schema:name', filter_value='My first resource!', filter_type='in')
items
assert len(items['results']) > 0
assert 'my first resource!' in items['results'][0]['schema:name'][0]['@value'].lower()
'results'][0]['schema:name'][0]['@value'] items[
'My first resource!'
OmekaAPIClient.search_items
OmekaAPIClient.search_items (query, search_type='fulltext_search', page=1, **extra_filters)
Search for matching items.
Two search types are available:
* ’search- looks for an exact match of the query in a property value * 'fulltext_search
- looks for the occurance of the query anywhere
Parameters:
* query
- the text you want to search for
* search_type
- one of ‘fulltext_search’ or ‘search’
* page
- number of results page
Additional parameters:
* resource_template_id
- numeric identifier
* resource_class_id
- numeric identifier
* item_set_id
- numeric identifier
* is_public
- boolean, True or False
Returns a dict with the following values:
* total_results
- number of matching resources
* results
- a list of dicts, each containing a JSON-LD formatted representation of a resource
= omeka.search_items('My first resource!')
items 'total_results'] items[
14
assert items['total_results'] >= len(items['results'])
Adding items
To add resources to Omeka you need authenticate your API requests by supplying key_identity
and key_credential
tokens as parameters.
= OmekaAPIClient(
omeka_auth # api_url='https://timsherratt.org/collections/api',
=os.getenv('API_URL'),
api_url=os.getenv('KEY_IDENTITY'),
key_identity=os.getenv('KEY_CREDENTIAL'),
key_credential# use_cache=False
)
There are two stages in creating a new item:
- prepare a payload containing the item data in the format expected by Omeka
- upload the payload to Omeka
Prepare an item payload
OmekaAPIClient.prepare_item_payload
OmekaAPIClient.prepare_item_payload (terms)
Prepare an item payload, ready for upload.
Parameters:
* terms
: a dict of terms, values, and (optionally) data types
Returns:
* the payload dict
= {
test_item 'schema:name': [
{'value': 'My first resource!'
}
] }
= omeka_auth.prepare_item_payload(test_item)
payload payload
{'schema:name': [{'property_id': 2922,
'type': 'literal',
'@value': 'My first resource!'}]}
Each term in the payload should have values for property_id
and type
, and the property value should be included as either @id
or @value
depending on the data type.
= list(payload.values())[0][0]
first_property
assert 'property_id' in first_property
assert 'type' in first_property
assert '@value' in first_property or '@id' in first_property
One of the powerful features of Omeka S is the ability to create resource templates that define a set of properties for a particular type of item. We can use templates to help create our payload, ensuring that the terms and data types we supply match those expected by the template. This is useful for identifying potential problems before we upload to Omeka, especially as Omeka will sometimes just fail silently.
OmekaAPIClient.prepare_item_payload_using_template
OmekaAPIClient.prepare_item_payload_using_template (terms, template_id)
Prepare an item payload, checking the supplied terms and values against the specified template.
Note:
* terms that are not in the template will generate a warning and be dropped from the payload
* data types that don’t match the template definitions will generate a warning and the term will be dropped from the payload
* if no data type is supplied, a type that conforms with the template definition will be used
Parameters:
* terms
: a dict of terms, values, and (optionally) data types
* template_id
: Omeka’s internal numeric identifier for the template
Returns:
* the payload dict
Once you’ve created a payload, you can add paths to any media files that you want to be attached to the item.
= {
test_newspaper_item 'schema:name': [
{'value': 'nakamura196!'
}
] }
= omeka.get_template_by_label('Newspaper')
newspaper_template newspaper_template
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/resource_templates/2',
'@type': 'o:ResourceTemplate',
'o:id': 2,
'o:label': 'Newspaper',
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/resource_classes/26',
'o:id': 26},
'o:title_property': None,
'o:description_property': None,
'o:resource_template_property': [{'o:property': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/properties/1',
'o:id': 1},
'o:alternate_label': None,
'o:alternate_comment': None,
'o:data_type': [],
'o:is_required': False,
'o:is_private': False},
{'o:property': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/properties/4',
'o:id': 4},
'o:alternate_label': None,
'o:alternate_comment': None,
'o:data_type': [],
'o:is_required': False,
'o:is_private': False},
{'o:property': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/properties/2922',
'o:id': 2922},
'o:alternate_label': None,
'o:alternate_comment': None,
'o:data_type': [],
'o:is_required': False,
'o:is_private': False}]}
= omeka_auth.prepare_item_payload_using_template(test_newspaper_item, newspaper_template["o:id"])
test_newspaper_payload test_newspaper_payload
{'schema:name': [{'property_id': 2922,
'type': 'literal',
'@value': 'nakamura196!'}]}
assert test_newspaper_item['schema:name'][0]['value'] == test_newspaper_payload['schema:name'][0]['@value']
assert test_newspaper_payload['schema:name'][0]['type'] == 'literal'
OmekaAPIClient.add_iiif_to_payload
OmekaAPIClient.add_iiif_to_payload (payload, iiif_urls)
Add iiif urls to the item payload.
Parameters:
* payload
- the payload dict to be modified
* iiif_urls
- iiif urls to be uploaded
Returns:
* the modified payload dict
= omeka_auth.add_iiif_to_payload({}, iiif_urls=['https://www.dl.ndl.go.jp/api/iiif/3437686/R0000001/info.json']) payload_with_iiif
assert json.loads(payload_with_iiif['data'][1])
OmekaAPIClient.add_media_to_payload
OmekaAPIClient.add_media_to_payload (payload, media_files)
Add media files to the item payload.
Parameters:
* payload
- the payload dict to be modified
* media_files
- media files to be uploaded
The value of media_files
can be either:
* a list of paths to the image/media files (filename is used as title)
* a list of dicts, each containing title
, and path
values
The path values can either be strings or pathlib Paths.
Returns: * the modified payload dict
= omeka_auth.add_media_to_payload({}, media_files=['media/nla.news-article226799674-24144902.jpg']) payload_with_media
assert json.loads(payload_with_media['data'][1])
Upload the payload to Omeka and create a new item
OmekaAPIClient.add_item
OmekaAPIClient.add_item (payload, media_files=None, template_id=None, class_id=None, item_set_id=None)
Create a new item from the supplied payload, optionally uploading attached media files.
Parameters:
* payload
- a dict generated by prepare_item_payload()
or prepare_item_payload_using_template()
* media_files
- a list of paths pointing to media files, or a list of dicts with path
and title
values
* template_id
- internal Omeka identifier of a resource template you want to attach to this item
* class_id
- internal Omeka identifier of a resource class you want to attach to this item
* item_set_id
- internal Omeka identifier for an item set you want to add this item to
Returns:
* a dict providing the JSON-LD representation of the new item from Omeka
Add a simple item
= omeka_auth.add_item(payload)
new_item new_item
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items/8027',
'@type': 'o:Item',
'o:id': 8027,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': None,
'o:resource_template': None,
'o:thumbnail': None,
'o:title': None,
'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},
'o:created': {'@value': '2022-11-15T04:08:56+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:08:56+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:media': [],
'o:item_set': [],
'o:site': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/1',
'o:id': 1},
{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/2', 'o:id': 2}],
'schema:name': [{'type': 'literal',
'property_id': 2922,
'property_label': 'name',
'is_public': True,
'@value': 'My first resource!'}]}
assert new_item['@type'] == 'o:Item'
assert test_item['schema:name'][0]['value'] == new_item['schema:name'][0]['@value']
You can also add an item to an existing item set by supplying the item_set_id
parameter.
# Get a random item set id
= random.choice(omeka_auth.get_resources('item_sets')['results'])
random_item_set = random_item_set['o:id']
item_set_id
# Create a new item using the item set id
= new_item = omeka_auth.add_item(payload, item_set_id=item_set_id)
new_item_in_item_set
# Check that the ids match
assert new_item_in_item_set['o:item_set'][0]['o:id'] == item_set_id
Updating resources
OmekaAPIClient.delete_resource
OmekaAPIClient.delete_resource (resource_id, resource_type)
Deletes a resource. No confirmation is requested, so use carefully.
Parameters: * resource_id
- local Omeka identifier of the resource you want to delete * resource_type
- type of the resource (eg ‘items’)
Returns: * dict with JSON-LD representation of the deleted resource
# Get a random item from a list of items
= omeka.get_resources('items')
data = random.choice(data['results'])
random_item
try:
= omeka_auth.delete_resource(random_item['o:id'], 'items')
deleted_resource
# The id of the deleted item should be None
assert deleted_resource['o:id'] is None
# The titles of the random and deleted items should be the same
assert deleted_resource['o:title'] == random_item['o:title']
# Trying to get the random item should now raise an HTTP 404 error
with pytest.raises(requests.exceptions.HTTPError):
'o:id'], 'items')
omeka_auth.get_resource_by_id(random_item[
except Exception as e:
print(e)
<Response [500]>
500 Server Error: Internal Server Error for url: https://omekas.aws.ldas.jp/sandbox/api/items/917?key_identity=SizuLgHbsl5vHI95Eyko5jzK5W8fqns6&key_credential=f7Zfaaukc5j1WGkHw99i3bJCHR7ZK3rO
OmekaAPIClient.update_resource
OmekaAPIClient.update_resource (payload, resource_type='items')
Update an existing resource.
Parameters: * payload
- the updated resource data * resource_type
- the type of resource
To avoid problems, it’s generally easiest to retrieve the resource first, make your desired changes to it, then submit the updated resource as your payload.
= omeka_auth.filter_items_by_property(filter_property='schema:name', filter_type='ex')
data data
{'total_results': 5,
'results': [{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items/8024',
'@type': 'o:Item',
'o:id': 8024,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': None,
'o:resource_template': None,
'o:thumbnail': None,
'o:title': None,
'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},
'o:created': {'@value': '2022-11-15T04:06:06+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:06:06+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:media': [],
'o:item_set': [],
'o:site': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/1',
'o:id': 1},
{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/2', 'o:id': 2}],
'schema:name': [{'type': 'literal',
'property_id': 2922,
'property_label': 'name',
'is_public': True,
'@value': 'My first resource!',
'@language': 'ja'}]},
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items/8025',
'@type': 'o:Item',
'o:id': 8025,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': None,
'o:resource_template': None,
'o:thumbnail': None,
'o:title': None,
'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},
'o:created': {'@value': '2022-11-15T04:07:21+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:07:21+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:media': [],
'o:item_set': [],
'o:site': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/1',
'o:id': 1},
{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/2', 'o:id': 2}],
'schema:name': [{'type': 'literal',
'property_id': 2922,
'property_label': 'name',
'is_public': True,
'@value': 'My first resource!'}]},
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items/8026',
'@type': 'o:Item',
'o:id': 8026,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': None,
'o:resource_template': None,
'o:thumbnail': None,
'o:title': None,
'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},
'o:created': {'@value': '2022-11-15T04:07:40+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:07:40+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:media': [],
'o:item_set': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/item_sets/187',
'o:id': 187}],
'o:site': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/1',
'o:id': 1},
{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/2', 'o:id': 2}],
'schema:name': [{'type': 'literal',
'property_id': 2922,
'property_label': 'name',
'is_public': True,
'@value': 'My first resource!'}]},
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items/8027',
'@type': 'o:Item',
'o:id': 8027,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': None,
'o:resource_template': None,
'o:thumbnail': None,
'o:title': None,
'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},
'o:created': {'@value': '2022-11-15T04:08:56+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:08:56+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:media': [],
'o:item_set': [],
'o:site': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/1',
'o:id': 1},
{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/2', 'o:id': 2}],
'schema:name': [{'type': 'literal',
'property_id': 2922,
'property_label': 'name',
'is_public': True,
'@value': 'My first resource!'}]},
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items/8028',
'@type': 'o:Item',
'o:id': 8028,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': None,
'o:resource_template': None,
'o:thumbnail': None,
'o:title': None,
'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},
'o:created': {'@value': '2022-11-15T04:08:57+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:08:57+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:media': [],
'o:item_set': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/item_sets/187',
'o:id': 187}],
'o:site': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/1',
'o:id': 1},
{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/2', 'o:id': 2}],
'schema:name': [{'type': 'literal',
'property_id': 2922,
'property_label': 'name',
'is_public': True,
'@value': 'My first resource!'}]}]}
# Get a random item from a list of items
= omeka_auth.filter_items_by_property(filter_property='schema:name', filter_type='ex')
data = random.choice(data['results'])
random_item # Original title
= random_item['schema:name'][0]['@value']
title
# Copy and update the original item
= deepcopy(random_item)
new_item 'schema:name'][0]['@value'] = title + ' - UPDATED!'
new_item[
# Update the item
= omeka_auth.update_resource(new_item, 'items')
updated_item
# Display the updated title
= updated_item['schema:name'][0]['@value']
updated_title print(updated_title)
# The id of the original and upated items should be the same
assert random_item['o:id'] == updated_item['o:id']
# But the titles should be different
assert title != updated_item['schema:name'][0]['@value']
My first resource! - UPDATED!
OmekaAPIClient.add_media_to_item
OmekaAPIClient.add_media_to_item (item_id, media_file, payload={}, template_id=None, class_id=None)
Upload a media file and associate it with an existing item.
Parameters:
* item_id
- the Omeka id of the item this media file should be added to
* media_path
- a path to an image/media file (string or pathlib Path)
* payload
(optional) - metadata to attach to media object, either a dict generated by prepare_item_payload()
or prepare_item_payload_using_template()
, or a string which is used as the value for dcterms:title
.
* template_id
- internal Omeka identifier of a resource template you want to attach to this item
* class_id
- internal Omeka identifier of a resource class you want to attach to this item
Returns: * a dict providing a JSON-LD representation of the new media object
= OmekaAPIClient(
omeka_auth =os.getenv('API_URL'),
api_url=os.getenv('KEY_IDENTITY'),
key_identity=os.getenv('KEY_CREDENTIAL'),
key_credential=False
use_cache )
Add a media file to an item without any additional metadata.
# Get a random item from a list of items
= omeka_auth.get_resources('items')
data = random.choice(data['results'])
item = item['o:id']
item_id
# Add a new media file to the item
= omeka_auth.add_media_to_item(item_id, 'media/nla.news-article226799674-24144902.jpg')
media_resource
# Check that the media resource is the expected type
assert media_resource['@type'] == 'o:Media'
# Check that the media resource is linked to the item
assert media_resource['o:item']['o:id'] == item_id
Include a title for a new media item by supplying a string value to the payload
parameter.
# Add a new media file with a title to the item
= omeka_auth.add_media_to_item(item_id, 'media/nla.news-article226799674-24144902.jpg', payload='This has a title')
media_resource
# The title should be saved as dcterms:title
assert media_resource['dcterms:title'][0]['@value'] == 'This has a title'
Include more detailed metadata with a new media item by generating a payload and supplying it using the payload
parameter.
# Define some metadata
= {
media_metadata 'schema:name': ['This is a different title'],
'schema:identifier': ['myidis3']
}
# Convert metadata into an Omeka payload
= omeka_auth.prepare_item_payload(media_metadata)
media_payload
# Add a new media file with a metadata payload to the item
= omeka_auth.add_media_to_item(item_id, 'media/nla.news-article226799674-24144902.jpg', payload=media_payload)
media_resource
assert media_resource['schema:name'][0]['@value'] == 'This is a different title'
Use a specific resource template with the new media item by using the template_id
parameter.
# Get a random template from a list of available templates for testing
= omeka_auth.get_resources('resource_templates')
data = random.choice(data['results'])
template = template['o:id']
template_id
# Add a new media file and assign it to a template using the `template_id` parameter
= omeka_auth.add_media_to_item(item_id, 'media/nla.news-article226799674-24144902.jpg', payload=media_payload, template_id=template_id)
media_resource
# Check the new media object has the correct template id
assert media_resource['o:resource_template']['o:id'] == template_id
OmekaAPIClient.add_iiif_to_item
OmekaAPIClient.add_iiif_to_item (item_id, iiif_url, payload={}, template_id=None, class_id=None)
Upload a media file and associate it with an existing item.
Parameters:
* item_id
- the Omeka id of the item this media file should be added to
* iiif_url
- a url to a iiif image (string)
* payload
(optional) - metadata to attach to media object, either
a dict generated by prepare_item_payload()
or prepare_item_payload_using_template()
, or a string which is used as the value for dcterms:title
.
* template_id
- internal Omeka identifier of a resource template you want to attach to this item
* class_id
- internal Omeka identifier of a resource class you want to attach to this item
Returns: * a dict providing a JSON-LD representation of the new media object
= OmekaAPIClient(
omeka_auth =os.getenv('API_URL'),
api_url=os.getenv('KEY_IDENTITY'),
key_identity=os.getenv('KEY_CREDENTIAL'),
key_credential=False
use_cache )
# Get a random item from a list of items
= omeka_auth.get_resources('items')
data = random.choice(data['results'])
item = item['o:id']
item_id
# Add a new iiif url with a title to the item
= omeka_auth.add_iiif_to_item(item_id, 'https://www.dl.ndl.go.jp/api/iiif/3437686/R0000001/info.json', payload='This has a title')
media_resource
# Check that the media resource is the expected type
assert media_resource['@type'] == 'o:Media'
# Check that the media resource is linked to the item
assert media_resource['o:item']['o:id'] == item_id
# The title should be saved as dcterms:title
assert media_resource['dcterms:title'][0]['@value'] == 'This has a title'
OmekaAPIClient.add_marker_to_item
OmekaAPIClient.add_marker_to_item (item_id, coords=None, terms=None, label=None, media_id=None)
Add a map marker to an item. Requires the mapping
module to be installed.
Parameters:
* item_id
- identifier of item to add marker to
* coords
- list with coordinates in longitude, latitude order eg [151.209900, -33.865143]
* terms
- list with vocab terms containing longitude and latitude values eg [‘schema:longitude’, ‘schema:latitude’]
* label
- label for marker (defaults to item title)
* media_id
- identifier of media resource to display with marker
Returns:
* dict providing JSON-LD representation of marker
The Omeka Mapping module lets you associate an item with a location on a map. Once you have the module installed, you can use the Omeka API to add map markers to items.
# Get a random item from a list of items
= omeka_auth.get_resources('items')
data = random.choice(data['results'])
item = item['o:id']
item_id
# Add a marker using coords
= omeka_auth.add_marker_to_item(item_id, coords=[151.209900, -33.865143])
marker
assert marker['@type'] == 'o-module-mapping:Marker'
assert marker['o:item']['o:id'] == item_id
You can also read the map coordinates from the item itself. By default OmekaAPIClient.add_marker_to_item
will look for values in schema:longitude
and schema:latitude
, but you can specify the vocabulary terms that you want to look for.
Here we’ll create a simple item with values for schema:longitude
and schema:latitude
.
= {
test_place 'schema:name': [
{'value': 'Australia'
}
],'schema:longitude': [
{'value': '151.209900'
}
],'schema:latitude': [
{'value': '-33.865143'
}
],
}
= omeka_auth.prepare_item_payload(test_place)
payload = omeka_auth.add_item(payload) new_place
Now we can just call OmekaAPIClient.add_marker_to_item
without any coordinates, and it will get them from schema:longitude
and schema:latitude
.
= omeka_auth.add_marker_to_item(new_place['o:id'])
new_marker
assert new_marker['@type'] == 'o-module-mapping:Marker'
assert new_marker['o:item']['o:id'] == new_place['o:id']
assert new_marker['o-module-mapping:lat'] == -33.865143
Managing templates
Resource templates can be exported from one Omeka instance and imported into another. This is a really useful way of sharing and resuing data structures. However, exported templates can’t be uploaded via the API without some modification, as they don’t include Omeka numeric identifiers for referenced classes and properties. Before uploading them, we need to find the referenced classes and properties in the local Omeka instance, and insert the local identifiers into the payload.
Similarly, if custom vocabs are referenced in the exported template, they will need to be updated to include the vocab’s identifier in the new Omeka instance. Of course, you’ll need to make sure it’s installed first.
In general, you want to make sure that the any vocabs and data types referenced by the exported templates will be available in the new Omeka instance. So before you upload any templates you should check that:
- referenced vocabularies are already installed
- modules used in defining data types are installed ( eg the Numeric Data Types module provides additional data types such as
Timestamp
for dates - any custom vocabularies (created using the Custom Vocab are installed, along with the module itself of course
- the Value Suggest module is installed if the template includes references to the controlled vocabs it provides
OmekaAPIClient.prepare_template_payload
OmekaAPIClient.prepare_template_payload (template_file)
Insert local property, class, and vocab identifiers into a resource template exported from Omeka so that it can be uploaded to the local instance.
Parameters:
* template_file
- path to a template exported from Omeka (str or pathlib Path)
Returns:
* template payload with local identifiers inserted
= OmekaAPIClient(
omeka_auth =os.getenv('API_URL'),
api_url=os.getenv('KEY_IDENTITY'),
key_identity=os.getenv('KEY_CREDENTIAL'),
key_credential=False
use_cache )
= omeka_auth.prepare_template_payload('templates/Person.json')
template_payload
# Check the label
assert template_payload['o:label'] == 'Person'
# Check that there is a list of properties
assert len(template_payload['o:resource_template_property']) > 0
OmekaAPIClient.upload_template
OmekaAPIClient.upload_template (template_payload)
Upload a template exported from an instance of Omeka to the current local instance.
Parameters:
* template_payload
- dict payload generated by prepare_template_payload
Return:
* dict containing a JSON-LD representation of the uploaded template
# First we'll check to see if there's already a template with the label 'Person'
= omeka_auth.get_template_by_label('Person')
existing_template
# If there is we'll delete it
# Trying to upload a template with the same label as an existing template will generate an error
if existing_template:
= omeka_auth.delete_resource(existing_template['o:id'], 'resource_templates')
deleted
# Now we can add the new template
= omeka_auth.prepare_template_payload('templates/Person.json')
template_payload = omeka_auth.upload_template(template_payload)
new_template
# Result should be a 'ResourceTemplate
assert new_template['@type'] == 'o:ResourceTemplate'
# Label should be 'Person'
assert new_template['o:label'] == 'Person'
# It should have properties
assert len(new_template['o:resource_template_property']) > 0
<Response [200]>
OmekaAPIClient.localise_custom_vocabs
OmekaAPIClient.localise_custom_vocabs (data_types)
Check a list of data types for references to custom vocabs. If found, look for the local identifier of the custom vocab, and insert it into the data type information.
Requires the customvocab
module to be installed.
Parameters:
* data_types
- a list of data types from an exported template property
Returns:
* list of datatypes with local identifiers
# Data type example with ridiculously high customvocab id value
= [{'name': 'customvocab:200000', 'label': "Date qualifiers"}]
data_types
# Localise!
= omeka_auth.localise_custom_vocabs(data_types)
localised_data_types print(localised_data_types)
if len(localised_data_types) > 0:
# Localised data type should start with 'customvocab'
assert localised_data_types[0].startswith('customvocab:')
# The localised customvocab id should not be the same as the supplied one
assert localised_data_types[0] != data_types[0]['name']
['customvocab:1']
OmekaAPIClient.get_template_class_id
OmekaAPIClient.get_template_class_id (template)
Get the local id of the resource class associated with the supplied template.
Parameters:
* template
- dict from exported template
Returns:
* class identifier
# Load template from filesystem
= json.loads(Path('templates/Person.json').read_bytes())
template
= omeka_auth.get_resource_by_term('schema:Person', 'resource_classes')['o:id']
person_class_id
# Get resource id
= omeka_auth.get_template_class_id(template)
class_id
assert class_id == person_class_id
OmekaAPIClient.get_template_property_id
OmekaAPIClient.get_template_property_id (template, term)
Get the local id of the property associated with the supplied template.
Parameters:
* template
- dict from exported template
* term
- property term (eg ‘o:title_property’)
Returns:
* property identifier
# Load template from filesystem
= json.loads(Path('templates/Person.json').read_bytes())
template
# get the id of the schema:name property
= omeka_auth.get_resource_by_term('schema:name', 'properties')['o:id']
name_prop_id
# Get id of template property used for title
= omeka_auth.get_template_property_id(template, 'o:title_property')
prop_id
# The ids should be the same
assert prop_id == name_prop_id
Adding item sets
To add resources to Omeka you need authenticate your API requests by supplying key_identity
and key_credential
tokens as parameters.
= OmekaAPIClient(
omeka_auth # api_url='https://timsherratt.org/collections/api',
=os.getenv('API_URL'),
api_url=os.getenv('KEY_IDENTITY'),
key_identity=os.getenv('KEY_CREDENTIAL'),
key_credential=False
use_cache )
There are two stages in creating a new item set:
- prepare a payload containing the item set data in the format expected by Omeka
- upload the payload to Omeka
Prepare an item set payload
OmekaAPIClient.prepare_item_payload
OmekaAPIClient.prepare_item_payload (terms)
Prepare an item payload, ready for upload.
Parameters:
* terms
: a dict of terms, values, and (optionally) data types
Returns:
* the payload dict
= {
test_item_set 'dcterms:title': [
{'value': 'My first item set!'
}
] }
= omeka_auth.prepare_item_payload(test_item_set)
payload payload
{'dcterms:title': [{'property_id': 1,
'type': 'literal',
'@value': 'My first item set!'}]}
Upload the payload to Omeka and create a new item set
OmekaAPIClient.add_item_set
OmekaAPIClient.add_item_set (payload, template_id=None, class_id=None)
Create a new item from the supplied payload, optionally uploading attached media files.
Parameters:
* payload
- a dict generated by prepare_item_payload()
or prepare_item_payload_using_template()
* template_id
- internal Omeka identifier of a resource template you want to attach to this item
* class_id
- internal Omeka identifier of a resource class you want to attach to this item
Returns:
* a dict providing the JSON-LD representation of the new item from Omeka
Add a simple item set
= omeka_auth.add_item_set(payload)
new_item_set new_item_set
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/item_sets/8035',
'@type': 'o:ItemSet',
'o:id': 8035,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': None,
'o:resource_template': None,
'o:thumbnail': None,
'o:title': 'My first item set!',
'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},
'o:created': {'@value': '2022-11-15T04:09:57+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:09:57+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:is_open': False,
'o:items': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items?item_set_id=8035'},
'dcterms:title': [{'type': 'literal',
'property_id': 1,
'property_label': 'Title',
'is_public': True,
'@value': 'My first item set!'}]}
Utilities
OmekaAPIClient.format_resource_id
OmekaAPIClient.format_resource_id (resource_id, resource_type)
Generate a formatted id for the resource with the specified Omeka id number and resource type.
Parameters:
* resource_id
- numeric identifier used by Omeka for this resource
* resource_type
- one of Omeka’s resource types, eg: ‘items’, ‘properties’
Returns: * a dict with values for ‘@id’ and ‘o:id’
= omeka.format_resource_id(5, 'resource_templates')
id_url
= os.getenv('API_URL')
api_url
assert id_url == {
'@id': f'{api_url}/resource_templates/5',
'o:id': 5
}
OmekaAPIClient.prepare_property_value
OmekaAPIClient.prepare_property_value (value, property_id)
Formats a property value according to its datatype as expected by Omeka.
The formatted value can be used in a payload to create a new item.
Parameters:
* value
- a dict containing a value
and (optionally) a type
and lang
* property_id
- the numeric identifier of the property
Note that is no type
is supplied, ‘literal’ will be used by default.
Returns: * a dict with values for property_id
, type
, and either @id
or @value
.
= omeka_auth.get_property_id('schema:url')
prop_id = {'value': 'https://glam-workbench.net', 'type': 'uri'}
prop_value
= omeka_auth.prepare_property_value(prop_value, prop_id)
formatted_prop formatted_prop
{'property_id': 2995, 'type': 'uri', '@id': 'https://glam-workbench.net'}
assert prop_id == formatted_prop['property_id']
assert 'type' in formatted_prop
assert formatted_prop['@id'] == 'https://glam-workbench.net'
OmekaAPIClient.get_template_properties
OmekaAPIClient.get_template_properties (template_id)
List properties used by the specified template.
The resource template objects returned by the API don’t include property terms.
This function gets the additional details, and organises the properties in a dictionary, organised by term. This makes it easy to check if a particular term is used by a template.
Parameters:
* template_id
- numeric identifier for a template
Returns:
* a dict organised by property terms, with values for property_id
and type
= omeka_auth.get_template_by_label('Newspaper')['o:id']
template_id = omeka_auth.get_template_properties(template_id)
newspaper_properties
assert 'schema:name' in newspaper_properties
Example: adding a newspaper article from Trove
In the example below I’m going to manually step through the process of adding a new item to Omeka using the API in order to demonstrate the methods available. But of course the point of using the API is to automate such processes – joining together the individual steps so they can be embedded into your own systems or workflows. For a more detailed example that uploads Trove newspaper articles from a variety of sources, including Trove searches, Trove lists, and Zotero libraries, see the GLAM Workbench.
Let’s suppose we want to add this newspaper article in Trove to our Omeka instance. To take best advantage of Omeka’s linked data infrastructure, we’ll actually create two resources – one for the article, and one for the newspaper it was published in.
I’ve already created templates labelled ‘Newspaper’ and ‘Newspaper article’.
Let’s start with the newspaper. First we need to find out the numeric identifier Omeka is using for the Newspaper template. We can use OmekaAPIClient.get_template_by_label
to find out.
= OmekaAPIClient(
omeka_auth =os.getenv('API_URL'),
api_url=os.getenv('KEY_IDENTITY'),
key_identity=os.getenv('KEY_CREDENTIAL'),
key_credential=False
use_cache
)
= omeka_auth.get_template_by_label('Newspaper')['o:id']
newspaper_template_id newspaper_template_id
2
For convenience, we can get a summary of the properties used in the Newspaper template using OmekaAPIClient.get_template_properties
. This is useful if we want to check which properties are in use, and what data types are expected.
omeka_auth.get_template_properties(newspaper_template_id)
{'dcterms:title': {'property_id': 1,
'type': ['literal', 'uri', 'resource:item']},
'dcterms:description': {'property_id': 4,
'type': ['literal', 'uri', 'resource:item']},
'schema:name': {'property_id': 2922,
'type': ['literal', 'uri', 'resource:item']}}
The first step in preparing our data for upload is to create a dictionary, using the required property terms as keys. In this case, we’ll assign data about the newspaper to schema.name
and schema.url
.
= {
newspaper 'schema.name': [
{'type': 'literal',
'value': 'The Bendigo Independent (Vic. : 1891 - 1918)'
}
],'schema:url': [
{'type': 'literal',
'value': 'http://nla.gov.au/nla.news-title806'
}
] }
Now we can use this data to create a payload for upload to Omeka. OmekaAPIClient.prepare_item_payload_using_template
will check our data against the Newspaper template and build the payload.
= omeka_auth.prepare_item_payload_using_template(newspaper, newspaper_template_id) payload
Term schema.name not in template
Term schema:url not in template
Whoops! It seems we have some problems with our data file! First of all we’ve used a full stop, rather than a colon in schema:name
. Second, we’ve said the data type of schema:url
is ‘literal’, but if we check the template properties we’ll see it’ should be ‘uri’. Let’s make these changes.
= {
newspaper 'schema:name': [
{'type': 'literal',
'value': 'The Bendigo Independent (Vic. : 1891 - 1918)'
}
],'schema:url': [
{'type': 'uri',
'value': 'http://nla.gov.au/nla.news-title806'
}
] }
= omeka_auth.prepare_item_payload_using_template(newspaper, newspaper_template_id) payload
Term schema:url not in template
That seems better! Now we can examine the payload.
payload
{'schema:name': [{'property_id': 2922,
'type': 'literal',
'@value': 'The Bendigo Independent (Vic. : 1891 - 1918)'}]}
Notice how the values have been reformatted? They should now be ready to upload to Omeka using OmekaAPIClient.add_item
. We’ll supply both the payload and the newspaper template id.
= omeka_auth.add_item(payload, template_id=newspaper_template_id) newspaper_item
We can check the contents of newspaper_item
to make sure it’s been added succesfully.
newspaper_item
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items/8036',
'@type': ['o:Item', 'dctype:Image'],
'o:id': 8036,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/resource_classes/26',
'o:id': 26},
'o:resource_template': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/resource_templates/2',
'o:id': 2},
'o:thumbnail': None,
'o:title': None,
'thumbnail_display_urls': {'large': None, 'medium': None, 'square': None},
'o:created': {'@value': '2022-11-15T04:10:04+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:10:04+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:media': [],
'o:item_set': [],
'o:site': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/1',
'o:id': 1},
{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/2', 'o:id': 2}],
'schema:name': [{'type': 'literal',
'property_id': 2922,
'property_label': 'name',
'is_public': True,
'@value': 'The Bendigo Independent (Vic. : 1891 - 1918)'}]}
Great! Now what about the article? Again let’s start by having a look at the ‘Newspaper article’ template.
= omeka_auth.get_template_by_label('Newspaper article')['o:id']
article_template_id omeka_auth.get_template_properties(article_template_id)
{'dcterms:title': {'property_id': 1,
'type': ['literal', 'uri', 'resource:item']},
'dcterms:description': {'property_id': 4,
'type': ['literal', 'uri', 'resource:item']},
'schema:name': {'property_id': 2922,
'type': ['literal', 'uri', 'resource:item']},
'schema:isPartOf': {'property_id': 2271,
'type': ['literal', 'uri', 'resource:item']},
'schema:datePublished': {'property_id': 2027,
'type': ['literal', 'uri', 'resource:item']},
'schema:url': {'property_id': 2995,
'type': ['literal', 'uri', 'resource:item']}}
This time we’ll build our data file in stages.
# Create an empty dictionary
= {}
article
# Add value for schema:name
'schema:name'] = ["MR nakamura196'S PREDICTION. RENEWAL OF CYCLONE FORETOLD."] article[
You’ll notice that this time I’ve only included the value of the property, not the data type. This is because OmekaAPIClient.prepare_item_payload_using_template
will insert default data types if they’re not specified. The basic rules it uses if you don’t supply a data type are:
- if the template defines a default data type, use that
- if ‘literal’ is in the template’s list of expected data types, use that
- if ‘literal’ is not in the template’s list of expected data types print a warning asking the user to specify a data type and drop the property from the payload
In the case above, the ‘literal’ data type will be assigned to the schema:name
value.
To create a link between the article and the newspaper it was published in, we can use schema.isPartOf
. If we look in the list of template properties we see that this property expects a data type of ‘resource:item’.
'schema:isPartOf': {'property_id': 736, 'type': ['resource:item']}
The ‘resource:item’ data type means that the value will be an identifier pointing to another Omeka item. So we include the identifier of the newly-created newspaper record. Once again, the data type will be automatically added when we generate the payload.
'schema:isPartOf'] = [newspaper_item['o:id']] article[
Next we’ll add the publication date. To recognise dates as specific data types, you need to install the Numeric Data Types module. Once that’s done, you can set the ‘numeric:timestamp’ data type as the default for any date fields in your template. In the list of properties from the newspaper article template, you can see:
'schema:datePublished': {'property_id': 928, 'type': ['numeric:timestamp']}
The date value itself is supplied in a standard ISO format – ‘YYYY-MM-DD’.
'schema:datePublished'] = ['1918-03-14'] article[
Finally we’ll add a link to the article. Once again the template includes a default data type.
'schema:url': {'property_id': 393, 'type': ['uri']}
So we can just include the value.
'schema:url'] = ['http://nla.gov.au/nla.news-article226799674'] article[
Now that we’ve assembled the article metadata, we can generate a payload.
= omeka_auth.prepare_item_payload_using_template(article, article_template_id) article_payload
As you can see below, the default data types have been inserted into the payload, and some additional fields have been added to define the link to the newspaper item.
article_payload
{'schema:name': [{'property_id': 2922,
'type': 'literal',
'@value': "MR nakamura196'S PREDICTION. RENEWAL OF CYCLONE FORETOLD."}],
'schema:isPartOf': [{'property_id': 2271, 'type': 'literal', '@value': 8036}],
'schema:datePublished': [{'property_id': 2027,
'type': 'literal',
'@value': '1918-03-14'}],
'schema:url': [{'property_id': 2995,
'type': 'literal',
'@value': 'http://nla.gov.au/nla.news-article226799674'}]}
We could now go ahead and upload the payload to Omeka, but what if we want to include media files? In this case I have a JPG image of the article I want to attach. All you need to do is supply a list of paths pointing to media files using the media_files
parameter. The list can just include the paths as strings, in which case the file name will be used as the media object’s title. Alternatively, you can supply a list of dicts, each containing a path
and title
value.
# Create a list of paths pointing to media files
# The paths can be strings or pathlib Paths
= ['media/nla.news-article226799674-24144902.jpg']
media_files
# Include the media files when we upload the payload
= omeka_auth.add_item(article_payload, media_files=media_files, template_id=article_template_id) article_item
When we look at the uploaded item, we’ll see that the media files have been processed and added to the record.
article_item
{'@context': 'https://omekas.aws.ldas.jp/sandbox/api-context',
'@id': 'https://omekas.aws.ldas.jp/sandbox/api/items/8037',
'@type': ['o:Item', 'dctype:Image'],
'o:id': 8037,
'o:is_public': True,
'o:owner': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/users/1',
'o:id': 1},
'o:resource_class': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/resource_classes/26',
'o:id': 26},
'o:resource_template': {'@id': 'https://omekas.aws.ldas.jp/sandbox/api/resource_templates/4',
'o:id': 4},
'o:thumbnail': None,
'o:title': None,
'thumbnail_display_urls': {'large': 'https://omekas.aws.ldas.jp/sandbox/files/large/a4ea085cb0ad5ff1000f1e33092eeb15e4fbf107.jpg',
'medium': 'https://omekas.aws.ldas.jp/sandbox/files/medium/a4ea085cb0ad5ff1000f1e33092eeb15e4fbf107.jpg',
'square': 'https://omekas.aws.ldas.jp/sandbox/files/square/a4ea085cb0ad5ff1000f1e33092eeb15e4fbf107.jpg'},
'o:created': {'@value': '2022-11-15T04:10:10+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:modified': {'@value': '2022-11-15T04:10:10+00:00',
'@type': 'http://www.w3.org/2001/XMLSchema#dateTime'},
'o:media': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/media/8038',
'o:id': 8038}],
'o:item_set': [],
'o:site': [{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/1',
'o:id': 1},
{'@id': 'https://omekas.aws.ldas.jp/sandbox/api/sites/2', 'o:id': 2}],
'schema:name': [{'type': 'literal',
'property_id': 2922,
'property_label': 'name',
'is_public': True,
'@value': "MR nakamura196'S PREDICTION. RENEWAL OF CYCLONE FORETOLD."}],
'schema:datePublished': [{'type': 'literal',
'property_id': 2027,
'property_label': 'datePublished',
'is_public': True,
'@value': '1918-03-14'}],
'schema:url': [{'type': 'literal',
'property_id': 2995,
'property_label': 'url',
'is_public': True,
'@value': 'http://nla.gov.au/nla.news-article226799674'}]}