Jump to

• Request
• Response
• Examples

Assign a Metadata Collection to a File

post

/documents/api/1.2/files/{fileId}/metadata/{collectionName}

Associate an existing metadata collection with a specified file.

Note: To assign a global collection to a file, you must be the owner or have the manager role for the file. If it is a personal collection, you can assign only if you are the file's owner.

You must assign a collection to a particular file before you can assign values to the fields for the particular file. You can assign a collection to one or more files, and any file can have one or more collections assigned to it.

Request

Supported Media Types

• application/json
• application/xml

Path Parameters

• collectionName: string
  Name of the metadata collection to assign. For a user personal collection, it must start with Personal., such as Personal.MyCollection.
• fileId: string

  Globally unique identifier (GUID) for the file.

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

The request was fulfilled.

Body ()

Root Schema : FileCollectionResponse

Type: object

The response body includes information about the assign collection to a file operation.

Show Source

• errorCode(optional): number
  An error code of zero (0) indicates no errors.
• idList(optional): string
  Globally unique identifier (GUID) of the original file.
• type(optional): string
  Item type file.

{
    "description":"The response body includes information about the assign collection to a file operation.",
    "properties":{
        "idList":{
            "type":"string",
            "description":"Globally unique identifier (GUID) of the original file."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>file</code>."
        },
        "errorCode":{
            "type":"number",
            "description":"An error code of zero (0) indicates no errors."
        }
    }
}

Example Response (application/json)

{
    "idList":"D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "type":"file",
    "errorCode":"0"
}

400 Response

Request parameters are not formatted correctly.

403 Response

Forbidden if the user does not have read permission.

404 Response

File ID or collection name is not found.

Back to Top

Examples

The following example assigns the CollectionA metadata collection to the specified file.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/metadata/CollectionA

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "idList": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
  "type": "file"
}

Example 2

The following example assigns the Personal.CollectionA metadata collection to the specified file.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/metadata/Personal.CollectionA

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
  "errorCode": "0",
  "idList": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
  "type": "file"
}

Example 3

The following example attempts to assign a nonexistent metadata collection to the specified file.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/metadata/Personal.CollectionAB

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 404

JSON Response

{
    "errorCode": "-16",
    "errorKey": "!csUnableToSetMetadata!csMetaCollectionDoesntExist,Personal.CollectionAB",
    "errorMessage": "Unable to set metadata. Metadata Collection 'Personal.CollectionAB' is not defined.",    
    "type": "file"
    "idList": "D3C1C1F319CFE6B102095C5DT0000000000100000001",
    "title": "Unable to set metadata. Metadata Collection 'Personal.CollectionAB' is not defined."
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Example 4

The following example attempts to assign a metadata collection to the specified file using invalid characters in the name.

POST .../files/D3C1C1F319CFE6B102095C5DT0000000000100000001/metadata/Personal.CollectionA,B

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "errorCode": "-96",
    "errorKey": "!csCollectionNameInvalidCharacters,Personal.CollectionA\\,B",
    "errorMessage": "Invalid characters in the collection name 'Personal.CollectionA,B'."
    "title": "Invalid characters in the collection name 'Personal.CollectionA,B'.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Back to Top