Create Attachment
The Create Attachment operation creates an attachment for a document.
Request
| Method | Request URI | Description |
|---|---|---|
| POST | https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs/{doc-name}/attachments. | The {databaseaccount} is the name of the Azure Cosmos DB account created under your subscription. The {db-id} value is the user generated name/ID of the database, not the system generated ID (rid). The {coll-id} value is the name of the collection the document is contained in. The {doc-name} value is the name of the document associated with the attachment. |
Headers
See Common Azure Cosmos DB REST request headers for headers that are used by all Azure Cosmos DB requests.
| Header | Required | Type | Description |
|---|---|---|---|
| Slug | Optional | String | The name of the attachment. It is only required when raw media is submitted to the Azure Cosmos DB attachment storage. For more information, refer to AtomPub Protocol. |
Body
| Property | Required | Type | Description |
|---|---|---|---|
| id | Optional | String | Not Required to be set when attaching raw media. It is a user settable property. It is the unique name that identifies the attachment, that is, no two attachments share the same ID. The ID must not exceed 255 characters. |
| contentType | Optional | String | Not Required to be set when attaching raw media. It is a user settable property. It notes the content type of the attachment. When submitting the attachment bits as body, Cosmos DB sets the contentType to the type set in the Content-Type header. |
| Media | Optional | String | Not Required to be set when attaching raw media. It is the URL link or file path where the attachment resides. |
{
"id": "image_id",
"contentType": "image/jpg",
"media": "www.bing.com"
}
Response
Headers
See Common Azure Cosmos DB REST response headers for headers that are returned by all Azure Cosmos DB responses.
Status codes
The following table lists common status codes returned by this operation. For a full list of status codes, see HTTP Status Codes.
| HTTP status code | Description |
|---|---|
| 201 Created | The operation was successful. |
| 400 Bad Request | The JSON body is invalid. Check for missing curly brackets or quotes. |
| 409 Conflict | The ID or Slug provided for the new attachment has been taken by an existing attachment. |
| 413 Entity Too Large | The document size in the request exceeded the allowable document size in a request. |
Body
Creating an attachment results in the creation of an attachment resource with the following response body:
| Property | Description |
|---|---|
| _rid | It is a system generated property. The resource ID (_rid) is a unique identifier that is also hierarchical per the resource stack on the resource model. It is used internally for placement and navigation of the attachment resource. |
| _ts | It is a system generated property. It specifies the last updated timestamp of the resource. The value is a timestamp. |
| _self | It is a system generated property. It is the unique addressable URI for the resource. |
| _etag | It is a system generated property that specifies the resource etag required for optimistic concurrency control. |
{
"id": "image_id",
"contentType": "image/jpg",
"media": "www.bing.com",
"_rid": "Sl8fALN4sw4CAAAAAAAAAOnTcEc=",
"_ts": 1449606296,
"_self": "dbs\/Sl8fAA==\/colls\/Sl8fALN4sw4=\/docs\/Sl8fALN4sw4CAAAAAAAAAA==\/attachments\/Sl8fALN4sw4CAAAAAAAAAOnTcEc=",
"_etag": "\"060091c2-0000-0000-0000-56673c980000\""
}
Example
POST https://contosomarketing.documents.azure.com/dbs/volcanodb/colls/volcano1/docs/c3bb1fef-fcb1-56e3-0389-f88583c3ce0d/attachments HTTP/1.1
x-ms-session-token: 16
x-ms-date: Tue, 08 Dec 2015 20:24:56 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dQ8MDtRExrtOeDL5TSaHvXhPTNyKiRrrIC3IjTSpf958%3d
Cache-Control: no-cache
User-Agent: contoso/1.0
x-ms-version: 2015-08-06
Accept: application/json
Host: contosomarketing.documents.azure.com
Cookie: x-ms-session-token=16
Content-Length: 66
Expect: 100-continue
Connection: Keep-Alive
{
"id": "image_id",
"contentType": "image/jpg",
"media": "www.bing.com"
}
HTTP/1.1 201 Created
Cache-Control: no-store, no-cache
Pragma: no-cache
Content-Type: application/json
Server: Microsoft-HTTPAPI/2.0
x-ms-max-media-storage-usage-mb: 2048
x-ms-media-storage-usage-mb: 0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Sun, 29 Nov 2015 19:20:18.154 GMT
etag: "060091c2-0000-0000-0000-56673c980000"
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;
x-ms-resource-usage: documentSize=0;documentsSize=291;collectionSize=369;
x-ms-schemaversion: 1.1
x-ms-alt-content-path: dbs/volcanodb/colls/volcano1/docs/c3bb1fef-fcb1-56e3-0389-f88583c3ce0d
x-ms-content-path: Sl8fALN4sw4CAAAAAAAAAA==
x-ms-quorum-acked-lsn: 18
x-ms-session-token: 19
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 4.95
x-ms-serviceversion: version=1.5.57.3
x-ms-activity-id: c03c09bf-a791-4dad-b2f8-fa88fa1bce04
Set-Cookie: x-ms-session-token=19; Domain=contosomarketing.documents.azure.com; Path=/dbs/volcanodb/colls/volcano1
x-ms-gatewayversion: version=1.5.57.3
Date: Tue, 08 Dec 2015 20:24:57 GMT
Content-Length: 292
{
"id": "image_id",
"contentType": "image/jpg",
"media": "www.bing.com",
"_rid": "Sl8fALN4sw4CAAAAAAAAAOnTcEc=",
"_ts": 1449606296,
"_self": "dbs\/Sl8fAA==\/colls\/Sl8fALN4sw4=\/docs\/Sl8fALN4sw4CAAAAAAAAAA==\/attachments\/Sl8fALN4sw4CAAAAAAAAAOnTcEc=",
"_etag": "\"060091c2-0000-0000-0000-56673c980000\""
}
Remarks
There are two ways to create an attachment resource – post the media content to Cosmos DB like in the AtomPub Protocol, or post just the attachment metadata to media stored externally.
The first is to POST the raw media in the body payload to store it in the provided attachment storage under your Cosmos DB account. To create this type of attachment, you must include the raw attachment (video, audio, file, blob, etc.) as the body of the POST. Two headers must be set: Content-Type and Slug. The Content-Type header is set to the MIME type of the attachment while the Slug header is set to the name of the attachment.
The second way to create an attachment resource is to POST the attachment resource properties noting the type and media link of the attachment. Unlike the first type of attachment resource, you must not set the Content-Type and Slug headers.