MediaValet SDK Documentation

#project/mediavalet/mvdam

Introduction

MediaValet SDK is a Python module designed to simplify the interaction with the MediaValet API. It offers a streamlined approach for accessing and handling API functionalities.

Installation

pip install mvsdk

## Getting Started
Quickstart guide on setting up and authenticating with the MediaValet API.

### Authentication
```python
# Code snippet for authentication

Getting Started

Here’s an easy “Hello World” example.

Fetching Asset Data

import mvsdk
import json

# Set Authentication Variables
# These variables are available in your API dashboard
auth_url: str = ""
base_url: str = ""
username: str = ""
password: str = ""
client_id: str = ""
client_secret: str = ""

# Set AssetId to be interacted with
asset_id: str = ""

# Open an MVSDK handle
sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)

# Authenticate to MediaValet
data = {
    "grant_type": "password",
    "username": username,
    "password": password,
    "scope": "openid api offline_access",
    }

auth = {
        "client_id": client_id,
        "client_secret": client_secret
    }

session = sdk_handle.connect.auth(data=data, auth=auth)

# Get the asset specific metadata
asset_metadata = sdk_handle.asset.get(auth=session.access_token, object_id=asset_id)

# Get all instance metadata
existing_attributes = sdk_handle.attribute.get(auth=session.access_token)

# Map asset metadata to human readable metadata names
attributes = {}

for attribute_id in asset_metadata.json()["payload"]["attributes"]:
    attributes[existing_attributes[attribute_id]] = asset_metadata.json()["payload"]["attributes"][attribute_id]

# Present the result
print(f"Attributes for asset {asset_id}:\n{json.dumps(attributes, indent=4)}")

Advanced Usage

MediaValet supports a Batch endpoint to enable you to send many commands in a single call, moving the parallel processing to their compute rather than forcing you to do so as the consumer. This endpoint is powerful but nuanced. In order to make it simpler to use, this SDK allows you to instantiate a “batch” object, pack your requests into that and submit in a single call. Here’s an example of such a call:

import mvsdk
from mvsdk.rest.bulk import BulkRequest, BulkResponse

import json

# Set Authentication Variables
auth_url: str = ""
base_url: str = ""
username: str = ""
password: str = ""
client_id: str = ""
client_secret: str = ""

# Set AssetId to be interacted with
asset_id: str = ""

# Open an MVSDK handle
sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)

# Authenticate to MediaValet
data = {
    "grant_type": "password",
    "username": username,
    "password": password,
    "scope": "openid api offline_access",
    }

auth = {
        "client_id": client_id,
        "client_secret": client_secret
    }

session = sdk_handle.connect.auth(data=data, auth=auth)

# Get the asset specific metadata
asset_metadata = sdk_handle.asset.get(auth=session.access_token, object_id=asset_id)

# Get all instance metadata
existing_attributes = sdk_handle.attribute.get(auth=session.access_token)

# Map asset metadata to human readable metadata names
attributes = {}

for attribute_id in asset_metadata.json()["payload"]["attributes"]:
    attributes[existing_attributes[attribute_id]] = asset_metadata.json()["payload"]["attributes"][attribute_id]

# Build the BulkRequest
bulk_request = BulkRequest()

get_attribute_request = sdk_handle.asset.get_attributes(object_id=asset_id, bulk=True)

bulk_request.add_request(get_attribute_request)

# Send the BulkRequest object to the bulk handle
request = bulk_request.get_payload()

response = sdk_handle.bulk.post(
    headers=request["headers"], data=request["payload"], auth=session.access_token
)

bulk_response =  BulkResponse(response)
    
# Present the result
for response in bulk_response.get_response:
    print(f"Attributes for asset {asset_id}:\n{json.dumps(response, indent=4)}")

API Reference

Detailed documentation of the SDK's API.

Action Generic Data

All actions use the following, where it makes sense:

• Parameters auth = the session token generated at initialisation object_id = the id of the asset to be interacted with
• Return Type For simplicity, SDK returns the requests payload for all API interactions.

SDK Handle Initialisation

In order to interact with any SDK endpoint, you first need to initialise a session. An example of how to do this simply would be as follows:

import mvsdk

# Set Authentication Variables
auth_url: str = ""
base_url: str = ""
username: str = ""
password: str = ""
client_id: str = ""
client_secret: str = ""

# Open an MVSDK handle
sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)

# Authenticate to MediaValet
data = {
    "grant_type": "password",
    "username": username,
    "password": password,
    "scope": "openid api offline_access",
    }

auth = {
        "client_id": client_id,
        "client_secret": client_secret
    }

session = sdk_handle.connect.auth(data=data, auth=auth)

Once you have initialised the sdk_handle and session variable, you must use that authenticated token in all calls to the SDK, as shown below.

Asset

• Description The Asset method provides the user with the ability to directly interact with the asset. As MediaValet is a Digital Asset Management tool, by far the majority of the functionality and endpoints are based around the asset itself.
• Examples

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# Get(/download) an asset 
####
response = sdk_handle.asset.get(
	auth=session.access_token,
	object_id=asset_id
)

file_response = requests.get(response.json()["payload"]["media"]["download"])

try:
	with open("example_filename", "wb") as file:
		for data in file_response.iter_content(1024):
			file.write(data)
except IOError:
	print(f"Could not write file. Please check write permissions and try again.")

####
# Get the asset specific metadata
####
attributes = sdk_handle.asset.get_attributes(
	auth=access_token,
	object_id=asset_id
)

####
# Get the assets categories
####
categories = sdk_handle.asset.get_categories(
	auth=access_token,
	object_id=asset_id
)

####
# Get comments made on the asset
####
comments = sdk_handle.asset.get_comments(
	auth=access_token,
	object_id=asset_id
)

####
# Get the asset history
####
history = sdk_handle.asset.get_history(
	auth=access_token,
	object_id=asset_id
)

####
# Add keywords to an asset
####
sdk_handle.asset.create_keywords(
	auth=access_token,
	object_id=asset_id,
	data=["example1", "example2"]
)

####
# Get asset keywords
####
keywords = sdk_handle.asset.get_keywords(
	auth=access_token,
	object_id=asset_id
)

####
# Get asset renditions
####
renditions = sdk_handle.asset.get_renditions(
	auth=access_token,
	object_id=asset_id
)

Attribute

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# 
####

Bulk

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# 
####

Category

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# 
####

Connect

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# 
####

Direct Link

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# 
####

Keyword

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# Create keyword
####
self.sdk_handle.keyword.create(
	auth=access_token,
	data="example"
)

####
# Get keyword
####
keyword = sdk_handle.keyword.get(
	auth=access_token
)

Keyword Group

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# Get keyword group
####
keyword_group = sdk_handle.keyword_group.get(
	auth=access_token
)

Organisational Unit

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# Get current org unit
####
current_org_unit = sdk_handle.org_unit.get_current(
	auth=access_token
)

User

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# Get all users
####
users = sdk_handle.user.get_all(
	auth=access_token
)

####
# Get all approvers
####
approvers = sdk_handle.user.get_approvers(
	auth=access_token
)

####
# Get current user
####
current_user = sdk_handle.user.get_current(
	auth=access_token
)

####
# Get current user permissions
####
current_user_permissions = sdk_handle.user.get_current_permissions(
	auth=access_token
)

User Group

• Description

• Example

import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

####
# Get all user groups
####
renditions = sdk_handle.user_group.get(
	auth=access_token
)

Error Handling

Information on error responses and handling mechanisms.

Best Practices

Guidelines for effective and efficient use of the SDK.

Contribution Guidelines

Instructions for contributing to the SDK development.

License and Credits

License information and acknowledgements.

Contact and Support

Details for support and contact information.