Admin - InformationProtection SetLabelsAsAdmin

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 be a Fabric 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
{
  "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

{
  "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