Replace an Attachment

  • Article

There are two ways to replace an attachment resource – put the media content to Azure Cosmos DB like in the AtomPub Protocol, or put just the attachment metadata to media stored externally.

The first is to PUT the raw media in the body payload to store it in the provided attachment storage under your Cosmos DB account. To replace this type of attachment, developers include the raw attachment (video, audio, file, blob, etc.) as the body of the PUT. 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 replace an attachment resource is to PUT the attachment resource properties noting the type and media link of the attachment. Unlike the first type of attachment resource, the Content-Type and Slug headers are not to be set as the raw media is not part of the request payload.

Request

Method Request URI Description
PUT https:// {databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/docs/{doc-name}/attachments/{att-name} Note that the {databaseaccount} is the name of the 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. The {att-name} value is the name of the attachment to be replaced.

Headers

See Common Azure Cosmos DB REST request headers for headers that are used by all 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 Cosmos DB attachment storage. For more details, 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_2",  
    "contentType": "image/jpg",  
    "media": "www.microsoft.com"  
}

Response

Headers

See Common Azure Cosmos DB REST response headers for headers that are returned by all 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
200 Ok The operation was successful.
400 Bad Request The JSON body is invalid. Check for missing curly brackets or quotes.
404 Not Found The attachment to be replaced is no longer a resource, that is, the attachment has been deleted.
409 Conflict The ID provided for the 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

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_2",  
    "contentType": "image/jpg",  
    "media": "www.microsoft.com",  
    "_rid": "Sl8fALN4sw4CAAAAAAAAAOnTcEc=",  
    "_ts": 1449606442,  
    "_self": "dbs\/Sl8fAA==\/colls\/Sl8fALN4sw4=\/docs\/Sl8fALN4sw4CAAAAAAAAAA==\/attachments\/Sl8fALN4sw4CAAAAAAAAAOnTcEc=",  
    "_etag": "\"0600abc2-0000-0000-0000-56673d2a0000\""  
}

Example

PUT https://contosomarketing.documents.azure.com/dbs/volcanodb/colls/volcano1/docs/c3bb1fef-fcb1-56e3-0389-f88583c3ce0d/attachments/image_id HTTP/1.1  
x-ms-session-token: 19  
x-ms-date: Tue, 08 Dec 2015 20:27:23 GMT  
authorization: type%3dmaster%26ver%3d1.0%26sig%3dKQWBkCCXyJ66fwBe9%2b%2b7oN7CSlIkMMyFEgimGDPawCs%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=19  
Content-Length: 281  
Expect: 100-continue  
  
{  
    "id": "image_id_2",  
    "contentType": "image/jpg",  
    "media": "www.microsoft.com"  
}  
  

HTTP/1.1 200 Ok  
Cache-Control: no-store, no-cache  
Pragma: no-cache  
Content-Type: application/json  
Content-Location: https://contosomarketing.documents.azure.com/dbs/volcanodb/colls/volcano1/docs/c3bb1fef-fcb1-56e3-0389-f88583c3ce0d/attachments/image_id  
Server: Microsoft-HTTPAPI/2.0  
Strict-Transport-Security: max-age=31536000  
x-ms-last-state-change-utc: Sun, 29 Nov 2015 19:20:18.154 GMT  
etag: "0600abc2-0000-0000-0000-56673d2a0000"  
x-ms-resource-quota: documentSize=10240;documentsSize=10485760;collectionSize=10485760;  
x-ms-resource-usage: documentSize=0;documentsSize=289;collectionSize=367;  
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: 19  
x-ms-session-token: 20  
x-ms-current-write-quorum: 3  
x-ms-current-replica-set-size: 4  
x-ms-request-charge: 9.9  
x-ms-serviceversion: version=1.5.57.3  
x-ms-activity-id: 8b8be54a-3c7e-4484-9f65-3a3d778347cc  
Set-Cookie: x-ms-session-token=20; Domain=contosomarketing.documents.azure.com; Path=/dbs/volcanodb/colls/volcano1  
x-ms-gatewayversion: version=1.5.57.3  
Date: Tue, 08 Dec 2015 20:27:24 GMT  
Content-Length: 299  
  
{  
    "id": "image_id_2",  
    "contentType": "image/jpg",  
    "media": "www.microsoft.com",  
    "_rid": "Sl8fALN4sw4CAAAAAAAAAOnTcEc=",  
    "_ts": 1449606442,  
    "_self": "dbs\/Sl8fAA==\/colls\/Sl8fALN4sw4=\/docs\/Sl8fALN4sw4CAAAAAAAAAA==\/attachments\/Sl8fALN4sw4CAAAAAAAAAOnTcEc=",  
    "_etag": "\"0600abc2-0000-0000-0000-56673d2a0000\""  
}

See Also