# Drive API . permissions

## Instance Methods

Deletes a permission from a file.

Gets a permission by ID.

Returns the permission ID for an email address.

Inserts a permission for a file.

Lists a file's permissions.

Updates a permission using patch semantics.

Updates a permission.

### Method Details

`delete(fileId, permissionId)`

    Deletes a permission from a file.

    Args:
      fileId: string, The ID for the file. (required)
      permissionId: string, The ID for the permission. (required)

`get(fileId, permissionId)`

    Gets a permission by ID.

    Args:
      fileId: string, The ID for the file. (required)
      permissionId: string, The ID for the permission. (required)

    Returns:
      An object of the form:

        { # A permission for a file.
        "withLink": True or False, # Whether the link is required for this permission.
        "domain": "A String", # The domain name of the entity this permission refers to. This is an output-only field which is present when the permission type is user, group or domain.
        "name": "A String", # The name for this permission.
        "kind": "drive#permission", # This is always drive#permission.
        "value": "A String", # The email address or domain name for the entity. This is used during inserts and is not populated in responses. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
        "id": "A String", # The ID of the user this permission refers to, and identical to the permissionId in the About and Files resources. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
        "authKey": "A String", # The authkey parameter required for this permission.
        "etag": "A String", # The ETag of the permission.
        "emailAddress": "A String", # The email address of the user or group this permission refers to. This is an output-only field which is present when the permission type is user or group.
        "photoLink": "A String", # A link to the profile photo, if available.
        "role": "A String", # The primary role for this user. Allowed values are:
            # - owner
            # - reader
            # - writer
        "type": "A String", # The account type. Allowed values are:
            # - user
            # - group
            # - domain
            # - anyone
        "additionalRoles": [ # Additional roles for this user. Only commenter is currently allowed.
          "A String",
        ],
        "selfLink": "A String", # A link back to this permission.
      }

`getIdForEmail(email)`

    Returns the permission ID for an email address.

    Args:
      email: string, The email address for which to return a permission ID (required)

    Returns:
      An object of the form:

        { # An ID for a user or group as seen in Permission items.
        "kind": "drive#permissionId", # This is always drive#permissionId.
        "id": "A String", # The permission ID.
      }

`insert(fileId, body, sendNotificationEmails=None, emailMessage=None)`

    Inserts a permission for a file.

    Args:
      fileId: string, The ID for the file. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # A permission for a file.
      "withLink": True or False, # Whether the link is required for this permission.
      "domain": "A String", # The domain name of the entity this permission refers to. This is an output-only field which is present when the permission type is user, group or domain.
      "name": "A String", # The name for this permission.
      "kind": "drive#permission", # This is always drive#permission.
      "value": "A String", # The email address or domain name for the entity. This is used during inserts and is not populated in responses. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
      "id": "A String", # The ID of the user this permission refers to, and identical to the permissionId in the About and Files resources. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
      "authKey": "A String", # The authkey parameter required for this permission.
      "etag": "A String", # The ETag of the permission.
      "emailAddress": "A String", # The email address of the user or group this permission refers to. This is an output-only field which is present when the permission type is user or group.
      "photoLink": "A String", # A link to the profile photo, if available.
      "role": "A String", # The primary role for this user. Allowed values are:
          # - owner
          # - reader
          # - writer
      "type": "A String", # The account type. Allowed values are:
          # - user
          # - group
          # - domain
          # - anyone
      "additionalRoles": [ # Additional roles for this user. Only commenter is currently allowed.
        "A String",
      ],
      "selfLink": "A String", # A link back to this permission.
    }

      sendNotificationEmails: boolean, Whether to send notification emails when sharing to users or groups. This parameter is ignored and an email is sent if the role is owner.
      emailMessage: string, A custom message to include in notification emails.

    Returns:
      An object of the form:

        { # A permission for a file.
        "withLink": True or False, # Whether the link is required for this permission.
        "domain": "A String", # The domain name of the entity this permission refers to. This is an output-only field which is present when the permission type is user, group or domain.
        "name": "A String", # The name for this permission.
        "kind": "drive#permission", # This is always drive#permission.
        "value": "A String", # The email address or domain name for the entity. This is used during inserts and is not populated in responses. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
        "id": "A String", # The ID of the user this permission refers to, and identical to the permissionId in the About and Files resources. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
        "authKey": "A String", # The authkey parameter required for this permission.
        "etag": "A String", # The ETag of the permission.
        "emailAddress": "A String", # The email address of the user or group this permission refers to. This is an output-only field which is present when the permission type is user or group.
        "photoLink": "A String", # A link to the profile photo, if available.
        "role": "A String", # The primary role for this user. Allowed values are:
            # - owner
            # - reader
            # - writer
        "type": "A String", # The account type. Allowed values are:
            # - user
            # - group
            # - domain
            # - anyone
        "additionalRoles": [ # Additional roles for this user. Only commenter is currently allowed.
          "A String",
        ],
        "selfLink": "A String", # A link back to this permission.
      }

`list(fileId)`

    Lists a file's permissions.

    Args:
      fileId: string, The ID for the file. (required)

    Returns:
      An object of the form:

        { # A list of permissions associated with a file.
        "items": [ # The actual list of permissions.
          { # A permission for a file.
            "withLink": True or False, # Whether the link is required for this permission.
            "domain": "A String", # The domain name of the entity this permission refers to. This is an output-only field which is present when the permission type is user, group or domain.
            "name": "A String", # The name for this permission.
            "kind": "drive#permission", # This is always drive#permission.
            "value": "A String", # The email address or domain name for the entity. This is used during inserts and is not populated in responses. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
            "id": "A String", # The ID of the user this permission refers to, and identical to the permissionId in the About and Files resources. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
            "authKey": "A String", # The authkey parameter required for this permission.
            "etag": "A String", # The ETag of the permission.
            "emailAddress": "A String", # The email address of the user or group this permission refers to. This is an output-only field which is present when the permission type is user or group.
            "photoLink": "A String", # A link to the profile photo, if available.
            "role": "A String", # The primary role for this user. Allowed values are:
                # - owner
                # - reader
                # - writer
            "type": "A String", # The account type. Allowed values are:
                # - user
                # - group
                # - domain
                # - anyone
            "additionalRoles": [ # Additional roles for this user. Only commenter is currently allowed.
              "A String",
            ],
            "selfLink": "A String", # A link back to this permission.
          },
        ],
        "kind": "drive#permissionList", # This is always drive#permissionList.
        "etag": "A String", # The ETag of the list.
        "selfLink": "A String", # A link back to this list.
      }

`patch(fileId, permissionId, body, transferOwnership=None)`

    Updates a permission using patch semantics.

    Args:
      fileId: string, The ID for the file. (required)
      permissionId: string, The ID for the permission. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # A permission for a file.
      "withLink": True or False, # Whether the link is required for this permission.
      "domain": "A String", # The domain name of the entity this permission refers to. This is an output-only field which is present when the permission type is user, group or domain.
      "name": "A String", # The name for this permission.
      "kind": "drive#permission", # This is always drive#permission.
      "value": "A String", # The email address or domain name for the entity. This is used during inserts and is not populated in responses. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
      "id": "A String", # The ID of the user this permission refers to, and identical to the permissionId in the About and Files resources. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
      "authKey": "A String", # The authkey parameter required for this permission.
      "etag": "A String", # The ETag of the permission.
      "emailAddress": "A String", # The email address of the user or group this permission refers to. This is an output-only field which is present when the permission type is user or group.
      "photoLink": "A String", # A link to the profile photo, if available.
      "role": "A String", # The primary role for this user. Allowed values are:
          # - owner
          # - reader
          # - writer
      "type": "A String", # The account type. Allowed values are:
          # - user
          # - group
          # - domain
          # - anyone
      "additionalRoles": [ # Additional roles for this user. Only commenter is currently allowed.
        "A String",
      ],
      "selfLink": "A String", # A link back to this permission.
    }

      transferOwnership: boolean, Whether changing a role to 'owner' downgrades the current owners to writers. Does nothing if the specified role is not 'owner'.

    Returns:
      An object of the form:

        { # A permission for a file.
        "withLink": True or False, # Whether the link is required for this permission.
        "domain": "A String", # The domain name of the entity this permission refers to. This is an output-only field which is present when the permission type is user, group or domain.
        "name": "A String", # The name for this permission.
        "kind": "drive#permission", # This is always drive#permission.
        "value": "A String", # The email address or domain name for the entity. This is used during inserts and is not populated in responses. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
        "id": "A String", # The ID of the user this permission refers to, and identical to the permissionId in the About and Files resources. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
        "authKey": "A String", # The authkey parameter required for this permission.
        "etag": "A String", # The ETag of the permission.
        "emailAddress": "A String", # The email address of the user or group this permission refers to. This is an output-only field which is present when the permission type is user or group.
        "photoLink": "A String", # A link to the profile photo, if available.
        "role": "A String", # The primary role for this user. Allowed values are:
            # - owner
            # - reader
            # - writer
        "type": "A String", # The account type. Allowed values are:
            # - user
            # - group
            # - domain
            # - anyone
        "additionalRoles": [ # Additional roles for this user. Only commenter is currently allowed.
          "A String",
        ],
        "selfLink": "A String", # A link back to this permission.
      }

`update(fileId, permissionId, body, transferOwnership=None)`

    Updates a permission.

    Args:
      fileId: string, The ID for the file. (required)
      permissionId: string, The ID for the permission. (required)
      body: object, The request body. (required)
        The object takes the form of:

    { # A permission for a file.
      "withLink": True or False, # Whether the link is required for this permission.
      "domain": "A String", # The domain name of the entity this permission refers to. This is an output-only field which is present when the permission type is user, group or domain.
      "name": "A String", # The name for this permission.
      "kind": "drive#permission", # This is always drive#permission.
      "value": "A String", # The email address or domain name for the entity. This is used during inserts and is not populated in responses. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
      "id": "A String", # The ID of the user this permission refers to, and identical to the permissionId in the About and Files resources. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
      "authKey": "A String", # The authkey parameter required for this permission.
      "etag": "A String", # The ETag of the permission.
      "emailAddress": "A String", # The email address of the user or group this permission refers to. This is an output-only field which is present when the permission type is user or group.
      "photoLink": "A String", # A link to the profile photo, if available.
      "role": "A String", # The primary role for this user. Allowed values are:
          # - owner
          # - reader
          # - writer
      "type": "A String", # The account type. Allowed values are:
          # - user
          # - group
          # - domain
          # - anyone
      "additionalRoles": [ # Additional roles for this user. Only commenter is currently allowed.
        "A String",
      ],
      "selfLink": "A String", # A link back to this permission.
    }

      transferOwnership: boolean, Whether changing a role to 'owner' downgrades the current owners to writers. Does nothing if the specified role is not 'owner'.

    Returns:
      An object of the form:

        { # A permission for a file.
        "withLink": True or False, # Whether the link is required for this permission.
        "domain": "A String", # The domain name of the entity this permission refers to. This is an output-only field which is present when the permission type is user, group or domain.
        "name": "A String", # The name for this permission.
        "kind": "drive#permission", # This is always drive#permission.
        "value": "A String", # The email address or domain name for the entity. This is used during inserts and is not populated in responses. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
        "id": "A String", # The ID of the user this permission refers to, and identical to the permissionId in the About and Files resources. When making a drive.permissions.insert request, exactly one of the id or value fields must be specified.
        "authKey": "A String", # The authkey parameter required for this permission.
        "etag": "A String", # The ETag of the permission.
        "emailAddress": "A String", # The email address of the user or group this permission refers to. This is an output-only field which is present when the permission type is user or group.
        "photoLink": "A String", # A link to the profile photo, if available.
        "role": "A String", # The primary role for this user. Allowed values are:
            # - owner
            # - reader
            # - writer
        "type": "A String", # The account type. Allowed values are:
            # - user
            # - group
            # - domain
            # - anyone
        "additionalRoles": [ # Additional roles for this user. Only commenter is currently allowed.
          "A String",
        ],
        "selfLink": "A String", # A link back to this permission.
      }