Add blobs to objects in Azure Digital Twins

Article
01/10/2020

Important

A new version of the Azure Digital Twins service has been released. In light of the new service's expanded capabilities, the original Azure Digital Twins service (described in this documentation set) has been retired.

To view the documentation for the new service, visit the active Azure Digital Twins Documentation.

Blobs are unstructured representations of common file types, like pictures and logs. Blobs track what kind of data they represent by using a MIME type (for example: "image/jpeg") and metadata (name, description, type, and so on).

Azure Digital Twins supports attaching blobs to devices, spaces, and users. Blobs can represent a profile picture for a user, a device photo, a video, a map, a firmware zip, JSON data, a log, etc.

This article assumes some familiarity with authenticating to your Azure Digital Twins Management APIs.

To learn more about authenticating with your Management APIs, read Authenticating with Azure Digital Twins APIs.
To authenticate with your Management APIs using the Postman REST client, read How to configure Postman.

Uploading blobs overview

You can use multipart requests to upload blobs to specific endpoints and their respective functionalities.

Note

Multipart requests typically require three pieces:

A Content-Type header:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
A Content-Disposition:
- form-data; name="metadata"
The file content to upload

Content-Type and Content-Disposition will vary depending on use scenario.

Multipart requests can be made programmatically (through C#), through a REST client, or tool such as Postman. REST client tools may have varying levels of support for complex multipart requests. Configuration settings may also vary slightly from tool to tool. Verify which tool is best suited for your needs.

Important

Multipart requests made to the Azure Digital Twins Management APIs typically have two parts:

Blob metadata (such as an associated MIME type) that's declared by Content-Type and/or Content-Disposition
Blob contents which include the unstructured contents of a file to be uploaded

Neither of the two parts is required for PATCH requests. Both are required for POST or create operations.

The Occupancy Quickstart source code contains complete C# examples demonstrating how to make multipart requests against the Azure Digital Twins Management APIs.

Blob metadata

In addition to Content-Type and Content-Disposition, Azure Digital Twins blob multipart requests must specify the correct JSON body. Which JSON body to submit depends on the kind of HTTP request operation that's being performed.

The four main JSON schemas are:

JSON blob metadata conforms to the following model:

{
    "parentId": "00000000-0000-0000-0000-000000000000",
    "name": "My First Blob",
    "type": "Map",
    "subtype": "GenericMap",
    "description": "A well chosen description",
    "sharing": "None"
  }

Attribute	Type	Description
parentId	String	The parent entity to associate the blob with (spaces, devices, or users)
name	String	A human-friendly name for the blob
type	String	The type of blob - cannot use type and typeId
typeId	Integer	The blob type ID - cannot use type and typeId
subtype	String	The blob subtype - cannot use subtype and subtypeId
subtypeId	Integer	The subtype ID for the blob - cannot use subtype and subtypeId
description	String	Customized description of the blob
sharing	String	Whether the blob can be shared - enum [`None`, `Tree`, `Global`]

Blob metadata is always supplied as the first chunk with Content-Type application/json or as a .json file. File data is supplied in the second chunk and can be of any supported MIME type.

The Swagger documentation describes these model schemas in full detail.

Tip

A Swagger sneak preview is provided to demonstrate the API feature set. It's hosted at docs.westcentralus.azuresmartspaces.net/management/swagger.

You can access your own generated Management API Swagger documentation at:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Name	Replace with
YOUR_INSTANCE_NAME	The name of your Azure Digital Twins instance
YOUR_LOCATION	Which server region your instance is hosted on

Learn about using the reference documentation by reading How to use Swagger.

Blobs response data

Individually returned blobs conform to the following JSON schema:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "parentId": "00000000-0000-0000-0000-000000000000",
  "type": "string",
  "subtype": "string",
  "typeId": 0,
  "subtypeId": 0,
  "sharing": "None",
  "description": "string",
  "contentInfos": [
    {
      "type": "string",
      "sizeBytes": 0,
      "mD5": "string",
      "version": "string",
      "lastModifiedUtc": "2019-01-12T00:58:08.689Z",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "fullName": "string",
  "spacePaths": [
    "string"
  ]
}

Attribute	Type	Description
id	String	The unique identifier for the blob
name	String	A human-friendly name for the blob
parentId	String	The parent entity to associate the blob with (spaces, devices, or users)
type	String	The type of blob - cannot use type and typeId
typeId	Integer	The blob type ID - cannot use type and typeId
subtype	String	The blob subtype - cannot use subtype and subtypeId
subtypeId	Integer	The subtype ID for the blob - cannot use subtype and subtypeId
sharing	String	Whether the blob can be shared - enum [`None`, `Tree`, `Global`]
description	String	Customized description of the blob
contentInfos	Array	Specifies unstructured metadata information including version
fullName	String	The full name of the blob
spacePaths	String	The space path

Blob metadata is always supplied as the first chunk with Content-Type application/json or as a .json file. File data is supplied in the second chunk and can be of any supported MIME type.

Blob multipart request examples

In the examples below, YOUR_MANAGEMENT_API_URL refers to the URI of the Digital Twins APIs:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Name	Replace with
YOUR_INSTANCE_NAME	The name of your Azure Digital Twins instance
YOUR_LOCATION	The region your instance is hosted on

To upload a text file as a blob and associate it with a space, make an authenticated HTTP POST request to:

YOUR_MANAGEMENT_API_URL/spaces/blobs

With the following body:

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "ParentId": "54213cf5-285f-e611-80c3-000d3a320e1e",
  "Name": "My First Blob",
  "Type": "Map",
  "SubType": "GenericMap",
  "Description": "A well chosen description",
  "Sharing": "None"
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="myblob.txt"
Content-Type: text/plain

This is my blob content. In this case, some text, but I could also be uploading a picture, an JSON file, a firmware zip, etc.

--USER_DEFINED_BOUNDARY--

Value	Replace with
USER_DEFINED_BOUNDARY	A multipart content boundary name

The following code is a .NET implementation of the same blob upload, using the class MultipartFormDataContent:

//Supply your metadata in a suitable format
var multipartContent = new MultipartFormDataContent("USER_DEFINED_BOUNDARY");

var metadataContent = new StringContent(JsonConvert.SerializeObject(metaData), Encoding.UTF8, "application/json");
metadataContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json; charset=utf-8");
multipartContent.Add(metadataContent, "metadata");

//MY_BLOB.txt is the String representation of your text file
var fileContents = new StringContent("MY_BLOB.txt");
fileContents.Headers.ContentType = MediaTypeHeaderValue.Parse("text/plain");
multipartContent.Add(fileContents, "contents");

var response = await httpClient.PostAsync("spaces/blobs", multipartContent);

Lastly, cURL users can make multipart form requests in the same manner:

curl -X POST "YOUR_MANAGEMENT_API_URL/spaces/blobs" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -H "Accept: application/json" \
 -H "Content-Type: multipart/form-data" \
 -F "meta={\"ParentId\":\"YOUR_SPACE_ID\",\"Name\":\"My CURL Blob\",\"Type\":\"Map\",\"SubType\":\"GenericMap\",\"Description\":\"A well chosen description\",\"Sharing\":\"None\"};type=application/json" \
 -F "text=PATH_TO_FILE;type=text/plain"

Value	Replace with
YOUR_TOKEN	Your valid OAuth 2.0 token
YOUR_SPACE_ID	The ID of the space to associate the blob with
PATH_TO_FILE	The path to your text file

A successful POST returns the ID of the new the blob.

API endpoints

The following sections describe the core blob-related API endpoints and their functionalities.

Devices

You can attach blobs to devices. The following image shows the Swagger reference documentation for your Management APIs. It specifies device-related API endpoints for blob consumption and any required path parameters to pass into them.

For example, to update or create a blob and attach the blob to a device, make an authenticated HTTP PATCH request to:

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

Parameter	Replace with
YOUR_BLOB_ID	The desired blob ID

Successful requests return a JSON object as described earlier.

Spaces

You can also attach blobs to spaces. The following image lists all space API endpoints responsible for handling blobs. It also lists any path parameters to pass into those endpoints.

For example, to return a blob attached to a space, make an authenticated HTTP GET request to:

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

Parameter	Replace with
YOUR_BLOB_ID	The desired blob ID

Successful requests return a JSON object as described earlier.

A PATCH request to the same endpoint updates metadata descriptions and creates versions of the blob. The HTTP request is made through the PATCH method, along with any necessary meta, and multipart form data.

Users

You can attach blobs to user models (for example, to associate a profile picture). The following image shows relevant user API endpoints and any required path parameters, like id:

For example, to fetch a blob attached to a user, make an authenticated HTTP GET request with any required form data to:

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

Parameter	Replace with
YOUR_BLOB_ID	The desired blob ID

Successful requests return a JSON object as described earlier.

Common errors

A common error involves not supplying the correct header information:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
To resolve this error, verify that the overall request has an appropriate Content-Type header:
- multipart/mixed
- multipart/form-data
Also, verify that each multipart chunk has an appropriate corresponding Content-Type.
A second common error arises when multiple blobs are assigned to the same resource in your spatial intelligence graph:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
Note

The message attribute will vary based on the resource.

Only one blob (of each kind) may be attached to each resource within your spatial graph.

To resolve this error, update the existing blob by using the appropriate API HTTP PATCH operation. Doing so will replace the existing blob data with the desired data.

Next steps

To learn more about Swagger reference documentation for Azure Digital Twins, read Use Azure Digital Twins Swagger.
To upload blobs through Postman, read How to configure Postman.

Add blobs to objects in Azure Digital Twins

Uploading blobs overview

Blob metadata

Blobs response data

Blob multipart request examples

API endpoints

Devices

Spaces

Users

Common errors

Next steps

Additional resources