Attach Twin Doc

This endpoint creates a copy of a Doc previously uploaded to temporary storage through an upload URL (see create_upload_url endpoint). The copy of the Doc is attached to the Twin and stored in the Twin's directory under the given "doc_name".

NOTE

In order to create a copy of a Doc and attach it to a Twin, the Doc needs to be already uploaded to temporary storage through an upload URL. The upload URL is returned in the response to the create_upload_url endpoint.

Method	Path	Operation*
POST	/twins/{twin}/docs	attach_twin_doc

*

In order for a user to perform the "attach_twin_doc" operation, the "attach_twin_doc" permission must be included in the list of allowed actions in the statement of the user's role.

Request

Parameter	Type	In	Description
{twin} required	string	path	Twin UUID.
doc_name required	string	body	Name of the Doc. It must match the regular expression(opens new window) ^([a-zA-Z0-9_-]{1,32}\/){0,5}([a-zA-Z0-9_-]{1,32})(.[a-zA-Z0-9]{1,8})?$. It must be unique in the context of the Twin.
hash optional *	string	body	SHA-256 hash(opens new window).
handler required	string	body	URL handler generated through the create_upload_url endpoint.
storage_class required	string, value is "access_optimized" or "cost_optimized", DEFAULT=access_optimized	body	Storage class of the Doc: - "access_optimized": Storage class for frequently accessed data. - "cost_optimized": Storage class for automatic cost savings for less frequently accessed data. Once the Doc has been copied and attached to the Twin, the "storage_class" cannot be changed.
description optional **	dictionary	body	User-defined key-value pairs: - key: It must match the regular expression(opens new window) ^[a-z_][0-9a-z_]{0,63}$. - value: JSON compliant value. If no fields have been added, the "description" attribute will not be displayed. For more details consult the description field section.

*

If the "hash" parameter is provided in the request, the method will check whether the hash provided by the user is equivalent to the hash generated for the Doc. If they don't match, a copy of the Doc will not be generated. Please note that the "status" of the Doc will have the value "copying" in the response to attaching the Doc to the Twin (attach_twin_doc endpoint). The "hash_mismatch" status will be returned when retrieving the Doc (get_twin_doc endpoint).

**

If no attributes are provided in the request body of "description" ("description": {}), the response will return an empty dictionary ("description": {}).

If "description" with the value null is provided in the request body, the response will not return the "description" field.

If the request body does not contain "description", the response will not return the "description" field.

In our example, we attach three Docs to the Twin. Each of the Docs will contain a copy of the file that we uploaded through the upload URL to temporary storage.

Response

Attribute	Type	Description
creation_certificate	dictionary	Certificate generated automatically by the system upon sending a request to copy the Doc (attach_twin_doc endpoint). It cannot be modified after it has been generated. Attribute Type Description created_ts timestamp Time at which the Doc was created. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window). creator string Account UUID of the account creating the Doc. hash * string SHA-256 hash(opens new window). size integer Size of the Doc in bytes.
storage_class	string, value can be "access_optimized" or "cost_optimized"	Storage class of the Doc: - "access_optimized": Storage class for frequently accessed data. - "cost_optimized": Storage class for automatic cost savings for less frequently accessed data. Once the Doc has been copied and attached to the Twin, the "storage_class" cannot be changed.
status	string, value can be "copying", "ok", "error", or "hash_mismatch"	Status of the Doc: - "copying": The Doc is in the process of being copied. - "ok": The copy of the Doc has been successfully generated. It is attached to the Twin and stored in the Twin's directory. - "hash_mismatch": The "hash" provided in the request does not match the hash of the Doc. A copy of the Doc could not be generated. - "error": An error occurred and a copy of the Doc could not be generated.
updated_ts	timestamp	Time at which the Doc was last updated. Measured in seconds (to three decimal places) that have elapsed since the Unix epoch(opens new window).
description	dictionary	User-defined key-value pairs: - key: It must match the regular expression(opens new window) ^[a-z_][0-9a-z_]{0,63}$. - value: JSON compliant value. For more details consult the description field section.

*

The "hash" attribute is only displayed in the "creation_certificate" if it was provided in the request to the attach_twin_doc endpoint.

Response ('Doc already exists')

NOTE

If you try to create a Doc that already exists, you will receive the error message "error": 'Doc already exists.'" for this Doc in the response. However, the response itself will return the 201 Created status code. Please see the below example for more details.

In our example, we want to attach two Docs to the Twin with the Twin UUID 3f359a50-65e2-4252-ba96-6fda5fe7e14c:

• The Doc with the name "Certifications/certification_2022_v1.txt". A Doc with the name "Certifications/certification_2022_v1.txt" is already attached to the Twin.
• The Doc with the name "Certifications/certification_2022_v1_copy3.txt". There is no Doc with this name attached to the Twin yet.

The response returns the message "error": "Doc already exists." for the Doc "Certifications/certification_2022_v1.txt", because a Doc with the name "Certifications/certification_2022_v1.txt" is already attached to the Twin. The status code of the response is 201 Created.

Response ('No Doc uploaded through the upload URL')

NOTE

If you have not uploaded a Doc through the upload URL, but try to attach a Doc, you will receive the error message "error": "No Doc uploaded through the upload URL - check handler []." for this Doc in the response. However, the response itself will return the 201 Created status code (see example below).

In our example, we want to attach a Doc with the name "Certifications/certification_2022_v3.txt" to the Twin with the Twin UUID 3f359a50-65e2-4252-ba96-6fda5fe7e14c. We have previously sent a PUT request to the upload URL. However, we have not attached a file to that request.

The response is the error message "error": "No Doc uploaded through the upload URL - check handler []."

Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status codes section.

Status code	Message	Comment
201	Created	If there is already a Doc with the given name attached to the Twin, you will receive the error: "error": "Doc already exists." for this Doc in the response. If you have not uploaded a Doc through the upload URL, but try to attach a Doc, you will receive the error message "error": "No Doc uploaded through the upload URL - check handler []." for this Doc in the response.