Files: modifyLabels

Modifies the set of labels on a file. Try it now.

Request

HTTP request

POST https://www.googleapis.com/drive/v3/files/fileId/modifyLabels

Parameters

Parameter name	Value	Description
Path parameters
`fileId`	`string`	The ID of the file for which the labels are modified.

Authorization

This request requires authorization with at least one of the following scopes:

Scope
`https://www.googleapis.com/auth/drive`
`https://www.googleapis.com/auth/drive.file`
`https://www.googleapis.com/auth/drive.metadata`

Some scopes are restricted and require a security assessment for your app to use them. For more information, see the authentication and authorization page.

Request body

In the request body, supply data with the following structure:

{
  "kind": "drive#modifyLabelsRequest",
  "labelModifications": [
    {
      "kind": "drive#labelModification",
      "labelId": string,
      "fieldModifications": [
        {
          "kind": "drive#labelFieldModification",
          "fieldId": string,
          "setTextValues": [
            string
          ],
          "setSelectionValues": [
            string
          ],
          "setIntegerValues": [
            long
          ],
          "setDateValues": [
            date
          ],
          "setUserValues": [
            string
          ],
          "unsetValues": boolean
        }
      ],
      "removeLabel": boolean
    }
  ]
}

Property name	Value	Description	Notes
`kind`	`string`	This is always drive#modifyLabelsRequest
`labelModifications[]`	`list`	The list of modifications to apply to the labels on the file.
`labelModifications[].kind`	`string`	This is always drive#labelModification.
`labelModifications[].labelId`	`string`	The ID of the label to modify.	writable
`labelModifications[].fieldModifications[]`	`list`	The list of modifications to this label's fields.	writable
`labelModifications[].fieldModifications[].kind`	`string`	This is always drive#labelFieldModification.
`labelModifications[].fieldModifications[].fieldId`	`string`	The ID of the Field to be modified.
`labelModifications[].fieldModifications[].setTextValues[]`	`list`	Replaces a `text` field with these new values.
`labelModifications[].fieldModifications[].setSelectionValues[]`	`list`	Replaces a `selection` field with these new values.
`labelModifications[].fieldModifications[].setIntegerValues[]`	`list`	Replaces an `integer` field with these new values.
`labelModifications[].fieldModifications[].setDateValues[]`	`list`	Replaces a `dateString` field with these new values. The values must be strings in the RFC 3339 full-date format: YYYY-MM-DD.
`labelModifications[].fieldModifications[].setUserValues[]`	`list`	Replaces a `user` field with these new values. The values must be valid email addresses.
`labelModifications[].fieldModifications[].unsetValues`	`boolean`	Unsets the values for this field.
`labelModifications[].removeLabel`	`boolean`	If true, the label will be removed from the file.	writable

Response

If successful, this method returns a response body with the following structure:

{
  "kind": "drive#modifyLabelsResponse",
  "modifiedLabels": [
    {
      "kind": "drive#label",
      "id": string,
      "revisionId": string,
      "fields": {
        (key): {
          "kind": "drive#labelField",
          "id": string,
          "valueType": string,
          "dateString": [
            date
          ],
          "integer": [
            long
          ],
          "selection": [
            string
          ],
          "text": [
            string
          ],
          "user": [
            {
              "kind": "drive#user",
              "displayName": string,
              "photoLink": string,
              "me": boolean,
              "permissionId": string,
              "emailAddress": string
            }
          ]
        }
      }
    }
  ]
}

Property name	Value	Description
`kind`	`string`	This is always drive#modifyLabelsResponse
`modifiedLabels[]`	`list`	The list of labels which were added or updated by the request.
`modifiedLabels[].kind`	`string`	This is always drive#label
`modifiedLabels[].id`	`string`	The ID of the label.
`modifiedLabels[].revisionId`	`string`	The revision ID of the label.
`modifiedLabels[].fields`	`object`	A map of the label's fields keyed by the field ID.
`modifiedLabels[].fields.(key)`	`nested object`
`modifiedLabels[].fields.(key).kind`	`string`	This is always drive#labelField.
`modifiedLabels[].fields.(key).id`	`string`	The identifier of this field.
`modifiedLabels[].fields.(key).valueType`	`string`	The field type. While new values may be supported in the future, the following are currently allowed: dateString integer selection text user
`modifiedLabels[].fields.(key).dateString[]`	`list`	Only present if `valueType` is `dateString`. RFC 3339 formatted date: YYYY-MM-DD.
`modifiedLabels[].fields.(key).integer[]`	`list`	Only present if `valueType` is `integer`.
`modifiedLabels[].fields.(key).selection[]`	`list`	Only present if `valueType` is `selection`.
`modifiedLabels[].fields.(key).text[]`	`list`	Only present if `valueType` is `text`.
`modifiedLabels[].fields.(key).user[]`	`list`	Only present if `valueType` is `user`.
`modifiedLabels[].fields.(key).user[].kind`	`string`	Identifies what kind of resource this is. Value: the fixed string `"drive#user"`.
`modifiedLabels[].fields.(key).user[].displayName`	`string`	A plain text displayable name for this user.
`modifiedLabels[].fields.(key).user[].photoLink`	`string`	A link to the user's profile photo, if available.
`modifiedLabels[].fields.(key).user[].me`	`boolean`	Whether this user is the requesting user.
`modifiedLabels[].fields.(key).user[].permissionId`	`string`	The user's ID as visible in Permission resources.
`modifiedLabels[].fields.(key).user[].emailAddress`	`string`	The email address of the user. This may not be present in certain contexts if the user has not made their email address visible to the requester.

Try it!

Use the APIs Explorer below to call this method on live data and see the response.