Recently I was working on an IoT solution for an international Safety Products manufacturer. One of the micro-service we were designing was to handle updating of device software.

One of the requirements was to be able to have the software updates as close as possible to the device charging station. There software updates were archived into Zip files.

There are two methods for creating a Azure Cosmos DB Document Attachment.

Store the file as an attachment to a Document

The raw attachment is included as the body of the POST.
Two headers must be set:

  • Slug – The name of the attachment.
  • contentType – Set to the MIME type of the attachment.

Store the URL for the file in an attachment to a Document

The body for the POST include the following.

  • id – It is the unique name that identifies the attachment, i.e. no two attachments will share the same id. The id must not exceed 255 characters.
  • Media – This is the URL link or file path where the attachment resides.

INFO: You can read more about creating an attachment here

The following is an example

    "id": "device\A234",  
    "contentType": "application/x-zip-compressed",  
    "media": ""  

Which method works best?

Let’s see how they compare.

Storage Comparison

Service Global Distribution Storage Limitations
Blob Storage Only 1 region None Unlimited
Document Attachment Available for all Azure Regions Supported Limited to 2GB per Cosmos DB Account
Content Delivery Network (CDN) Available for all Azure Regions You can enable Azure Content Delivery Network (CDN) to cache content from Azure storage. Azure CDN offers developers a global solution for delivering high-bandwidth content. It can cache blobs and static content of compute instances at physical nodes in the United States, Europe, Asia, Australia, and South America. Unlimited


  • Since the total size of all the attachment files is an unknown, attaching the file to the document would not work.
  • Blob Storage is out since there is only one region available.
  • Because it supports caching and multi-region instances, Azure Content Delivery Network (CDN) is the only storage solutions that meets my client’s requirements