Add blobs to objects in Azure Digital Twins

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.

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.

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"
  }

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.

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

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

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"
  ]
}

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

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--

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"

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

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

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

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.