Admin - InformationProtection SetLabelsAsAdmin

Reference

Service:: Power BI REST APIs

API Version:: v1.0

Set sensitivity labels on Power BI items (such as reports or dashboards) by item ID.

To set a sensitivity label using this API, the admin user or the delegated user (if provided) must have the label included in their label policy. For a usage example, see Set or remove sensitivity labels.

Permissions

The user must have administrator rights (such as Office 365 Global Administrator or Power BI Service Administrator).
The admin user and the delegated user (if provided) must have sufficient usage rights to set labels.

Required Scope

Tenant.ReadWrite.All

Limitations

Maximum 25 requests per hour.
Each request can update up to 2,000 Power BI items.

POST https://api.powerbi.com/v1.0/myorg/admin/informationprotection/setLabels

Request Body

Name	Required	Type	Description
artifacts	True	InformationProtectionArtifactsChangeLabel	A composite of Power BI item IDs for each item type
labelId	True	string	The label ID, which must be in the user's label policy.
assignmentMethod		assignmentMethod	Specifies whether the assigned label was set by an automated process or manually.
delegatedUser		DelegatedUser	Delegated user details. A delegated user is a user within an organization whose admin sets a label on behalf of the user. Although the admin sets the label, the delegated user is marked as the label issuer.

Responses

Name	Type	Description
200 OK	InformationProtectionChangeLabelResponse	OK

Examples

Example

Sample Request

POST https://api.powerbi.com/v1.0/myorg/admin/informationprotection/setLabels

Request Body

{
  "artifacts": {
    "dashboards": [
      {
        "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542a"
      },
      {
        "id": "476fcafe-b514-495d-b13f-ca9a4f0b1d8b"
      }
    ],
    "reports": [
      {
        "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542c"
      }
    ],
    "datasets": [
      {
        "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542e"
      },
      {
        "id": "myDatabaseName"
      }
    ],
    "dataflows": [
      {
        "id": "476fcafe-b514-495d-b13f-ca9a4f0b1d8g"
      }
    ]
  },
  "labelId": "fe472f5e-636e-4c10-a1c6-7e9edc0b542p",
  "assignmentMethod": "Standard",
  "delegatedUser": {
    "emailAddress": "john@contoso.com"
  }
}

Sample Response

Status code:: 200

{
  "dashboards": [
    {
      "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542a",
      "status": "NotFound"
    },
    {
      "id": "476fcafe-b514-495d-b13f-ca9a4f0b1d8b",
      "status": "Failed"
    }
  ],
  "reports": [
    {
      "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542c",
      "status": "Succeeded"
    }
  ],
  "datasets": [
    {
      "id": "fe472f5e-636e-4c10-a1c6-7e9edc0b542e",
      "status": "InsufficientUsageRights"
    },
    {
      "id": "myDatabaseName",
      "status": "FailedToGetUsageRights"
    }
  ],
  "dataflows": [
    {
      "id": "476fcafe-b514-495d-b13f-ca9a4f0b1d8g",
      "status": "Succeeded"
    }
  ]
}

Definitions

Name	Description
ArtifactId	The unique ID of a Power BI item in UUID format. Dashboard, report, and dataflow IDs are in UUID format, and dataset IDs can be in UUID or string format.
ArtifactStringId	The unique ID of a Power BI item in string or UUID format. Dashboard, report, and dataflow IDs are in UUID format, and dataset IDs can be in UUID or string format.
assignmentMethod	Specifies whether the assigned label was set by an automated process or manually.
ChangeLabelStatus	The unique ID and information protection label change status of a Power BI item
DelegatedUser	Delegated user details. The user must be an existing user in Power BI and Azure AAD, and must have signed in to Power BI during the last three months.
InformationProtectionArtifactsChangeLabel	A composite of Power BI item IDs for each item type. The IDs specify which Power BI items require an information protection label update.
InformationProtectionChangeLabelDetails	A composite of label information required to update an information protection label
InformationProtectionChangeLabelResponse	A composite of the ID and information protection label change status for one or more Power BI items organized by type
status	The status of an information protection label change operation

ArtifactId

The unique ID of a Power BI item in UUID format. Dashboard, report, and dataflow IDs are in UUID format, and dataset IDs can be in UUID or string format.

Name	Type	Description
id	string	An ID in UUID format

ArtifactStringId

The unique ID of a Power BI item in string or UUID format. Dashboard, report, and dataflow IDs are in UUID format, and dataset IDs can be in UUID or string format.

Name	Type	Description
id	string	An ID in string or UUID format

assignmentMethod

Specifies whether the assigned label was set by an automated process or manually.

Name	Type	Description
Priviledged	string	The label was set manually
Standard	string	The label was set by an automated process (default value)

ChangeLabelStatus

The unique ID and information protection label change status of a Power BI item

Name	Type	Description
id	string	The unique ID of a Power BI item. The ID is in UUID format for dashboards, reports, and dataflows; and in UUID or string format for datasets.
status	status	The status of an information protection label change operation

DelegatedUser

Delegated user details. The user must be an existing user in Power BI and Azure AAD, and must have signed in to Power BI during the last three months.

Name	Type	Description
emailAddress	string	The email address of the delegated user

InformationProtectionArtifactsChangeLabel

A composite of Power BI item IDs for each item type. The IDs specify which Power BI items require an information protection label update.

Name	Type	Description
dashboards	ArtifactId[]	A list of unique dashboard IDs
dataflows	ArtifactId[]	A list of unique dataflow IDs
datasets	ArtifactStringId[]	A list of unique dataset IDs
reports	ArtifactId[]	A list of unique report IDs

InformationProtectionChangeLabelDetails

A composite of label information required to update an information protection label

Name	Type	Description
artifacts	InformationProtectionArtifactsChangeLabel	A composite of Power BI item IDs for each item type
assignmentMethod	assignmentMethod	Specifies whether the assigned label was set by an automated process or manually.
delegatedUser	DelegatedUser	Delegated user details. A delegated user is a user within an organization whose admin sets a label on behalf of the user. Although the admin sets the label, the delegated user is marked as the label issuer.
labelId	string	The label ID, which must be in the user's label policy.

InformationProtectionChangeLabelResponse

A composite of the ID and information protection label change status for one or more Power BI items organized by type

Name	Type	Description
dashboards	ChangeLabelStatus[]	A list containing the unique ID and information protection label change status of one or more dashboards
dataflows	ChangeLabelStatus[]	A list containing the unique ID and information protection label change status of one or more dataflows
datasets	ChangeLabelStatus[]	A list containing the unique ID and information protection label change status of one or more datasets
reports	ChangeLabelStatus[]	A list containing the unique ID and information protection label change status of one or more reports

status

The status of an information protection label change operation

Name	Type	Description
Failed	string	Failed to set a new label. Please retry.
FailedToGetUsageRights	string	Failed to set a new label. The Power BI item has a sensitivity label with protection settings, and Power BI was unable to verify that the user has sufficient usage rights to change the label.
InsufficientUsageRights	string	Failed to set a new label. The Power BI item has a sensitivity label with protection settings, and the admin user (and the delegated user, if provided) doesn't have sufficient usage rights to change the label.
NotFound	string	The Power BI item ID or label wasn't found
Succeeded	string	The Power BI item label was changed