Zdieľať cez

Admin - Get Refreshables

  • Reference
Service:
Power BI REST APIs
API Version:
v1.0

Returns a list of refreshables for the organization within a capacity.

Power BI retains a seven-day refresh history for each dataset, up to a maximum of sixty refreshes.

Permissions

  • The user must be a Fabric administrator or authenticate using a service principal.
  • Delegated permissions are supported.

When running under service prinicipal authentication, an app must not have any admin-consent required premissions for Power BI set on it in the Azure portal.

Required Scope

Tenant.Read.All or Tenant.ReadWrite.All

Relevant only when authenticating via a standard delegated admin access token. Must not be present when authentication via a service principal is used.

Limitations

Maximum 200 requests per hour.

GET https://api.powerbi.com/v1.0/myorg/admin/capacities/refreshables?$top={$top}
With optional parameters: 
GET https://api.powerbi.com/v1.0/myorg/admin/capacities/refreshables?$expand={$expand}&$filter={$filter}&$top={$top}&$skip={$skip}

URI Parameters

Name In Required Type Description
$top
 query True

integer (int32)

minimum: 1

Returns only the first n results.
$expand
 query

string

Accepts a comma-separated list of data types, which will be expanded inline in the response. Supports capacities and groups.
$filter
 query

string

Returns a subset of a results based on Odata filter query parameter condition.
$skip
 query

integer (int32)

Skips the first n results. Use with top to fetch results beyond the first 1000.

Responses

Name Type Description
200 OK

Refreshables

OK

Examples

Example
Get refreshables, filtering for an average refresh duration of greater than 30 minutes example.
Get refreshables with their 'capacity' and 'group' expanded example

Example

Sample request

GET https://api.powerbi.com/v1.0/myorg/admin/capacities/refreshables

Sample response

Status code:
200 
{
  "value": [
    {
      "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
      "name": "SalesMarketing",
      "kind": "Dataset",
      "startTime": "2017-06-13T09:25:43.153Z",
      "endTime": "2017-06-19T11:22:32.445Z",
      "refreshCount": 22,
      "refreshFailures": 0,
      "averageDuration": 289.3814,
      "medianDuration": 268.6245,
      "refreshesPerDay": 11,
      "lastRefresh": {
        "refreshType": "ViaApi",
        "startTime": "2017-06-13T09:25:43.153Z",
        "endTime": "2017-06-13T09:31:43.153Z",
        "status": "Completed",
        "requestId": "9399bb89-25d1-44f8-8576-136d7e9014b1"
      },
      "refreshSchedule": {
        "days": [
          "Sunday",
          "Friday",
          "Saturday"
        ],
        "times": [
          "05:00",
          "11:30",
          "17:30",
          "23:00"
        ],
        "enabled": true,
        "localTimeZoneId": "UTC",
        "notifyOption": "MailOnFailure"
      },
      "configuredBy": [
        "john@contoso.com"
      ]
    }
  ]
}

Get refreshables, filtering for an average refresh duration of greater than 30 minutes example.

Sample request

GET https://api.powerbi.com/v1.0/myorg/admin/capacities/refreshables?$filter=averageDuration gt 1800

Sample response

Status code:
200 
{
  "value": [
    {
      "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
      "name": "SalesMarketing",
      "kind": "Dataset",
      "startTime": "2017-06-13T09:25:43.153Z",
      "endTime": "2017-06-19T11:22:32.445Z",
      "refreshCount": 22,
      "refreshFailures": 0,
      "averageDuration": 3289.3814,
      "medianDuration": 2268.6245,
      "refreshesPerDay": 11,
      "lastRefresh": {
        "refreshType": "ViaApi",
        "startTime": "2017-06-13T09:25:43.153Z",
        "endTime": "2017-06-13T09:58:05.221Z",
        "status": "Completed",
        "requestId": "9399bb89-25d1-44f8-8576-136d7e9014b1"
      },
      "refreshSchedule": {
        "days": [
          "Sunday",
          "Friday",
          "Saturday"
        ],
        "times": [
          "05:00",
          "11:30",
          "17:30",
          "23:00"
        ],
        "enabled": true,
        "localTimeZoneId": "UTC",
        "notifyOption": "MailOnFailure"
      },
      "configuredBy": [
        "john@contoso.com"
      ]
    }
  ]
}

Get refreshables with their 'capacity' and 'group' expanded example

Sample request

GET https://api.powerbi.com/v1.0/myorg/admin/capacities/refreshables?$expand=capacity,group

Sample response

Status code:
200 
{
  "value": [
    {
      "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
      "name": "SalesMarketing",
      "kind": "Dataset",
      "startTime": "2017-06-13T09:25:43.153Z",
      "endTime": "2017-06-19T11:22:32.445Z",
      "refreshCount": 22,
      "refreshFailures": 0,
      "averageDuration": 289.3814,
      "medianDuration": 268.6245,
      "refreshesPerDay": 11,
      "lastRefresh": {
        "refreshType": "ViaApi",
        "startTime": "2017-06-13T09:25:43.153Z",
        "endTime": "2017-06-13T09:31:43.153Z",
        "status": "Completed",
        "requestId": "9399bb89-25d1-44f8-8576-136d7e9014b1"
      },
      "refreshSchedule": {
        "days": [
          "Sunday",
          "Friday",
          "Saturday"
        ],
        "times": [
          "05:00",
          "11:30",
          "17:30",
          "23:00"
        ],
        "enabled": true,
        "localTimeZoneId": "UTC",
        "notifyOption": "MailOnFailure"
      },
      "configuredBy": [
        "john@contoso.com"
      ],
      "capacity": {
        "id": "0f084df7-c13d-451b-af5f-ed0c466403b2",
        "displayName": "MyCapacity",
        "sku": "A1"
      },
      "group": {
        "id": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
        "name": "SalesMarketing"
      }
    }
  ]
}

Definitions

Name Description
Capacity

A Power BI capacity
CapacityState

The capacity state
capacityUserAccessRight

The access right that the user has on the capacity
days

The days on which to execute the refresh
Refresh

A Power BI refresh history entry
Refreshable

A Power BI refreshable is a dataset that's been refreshed at least once, or for which a valid refresh schedule exists. If a dataset doesn't meet either of these conditions, then it won't show up in the API response. Power BI retains a seven-day refresh history for each dataset, up to a maximum of sixty refreshes.
RefreshableGroup

A Power BI group associated to a Refreshable item
RefreshableKind

The refreshable kind
Refreshables

A Power BI refreshables list
RefreshAttempt

Power BI automatically makes multiple attempts to refresh a dataset if it experiences a refresh failure. This object contains information about each refresh attempt.
RefreshAttemptType

The type of refresh attempt.
RefreshSchedule

A Power BI refresh schedule for imported model
RefreshType

The type of refresh request
ScheduleNotifyOption

The notification option on termination of a scheduled refresh. Service principals only support the NoNotification value.
TenantKey

Encryption key information

Capacity

Object

A Power BI capacity

Name Type Description
admins

string[]

An array of capacity admins
capacityUserAccessRight

capacityUserAccessRight

The access right a user has on the capacity
displayName

string

The display name of the capacity
id

string (uuid)

The capacity ID
region

string

The Azure region where the capacity was provisioned
sku

string

The capacity SKU
state

CapacityState

The capacity state
tenantKey

TenantKey

Encryption key information (only applies to admin routes)
tenantKeyId

string (uuid)

The ID of an encryption key (only applicable to the admin route)

CapacityState

Enumeration

The capacity state

Value Description
Active

The capacity is ready to use
Deleted

The capacity was deleted and is unavailable
Deleting

Deletion of the capacity is in progress
Invalid

The capacity can't be used
NotActivated

Unsupported
PreSuspended

Unsupported
ProvisionFailed

Provisioning of the capacity failed
Provisioning

Activation of the capacity is in progress
Suspended

Use of the capacity is suspended
UpdatingSku

A capacity SKU change is in progress

capacityUserAccessRight

Enumeration

The access right that the user has on the capacity

Value Description
Admin

User has administrator rights on the capacity
Assign

User has contributor rights and can assign workspaces to the capacity
None

User doesn't have access to the capacity

days

Enumeration

The days on which to execute the refresh

Value Description
Friday
Monday
Saturday
Sunday
Thursday
Tuesday
Wednesday

Refresh

Object

A Power BI refresh history entry

Name Type Description
endTime

string (date-time)

The end date and time of the refresh (may be empty if a refresh is in progress) in UTC format.
refreshAttempts

RefreshAttempt[]

The refresh attempt list.
refreshType

RefreshType

The type of refresh request
requestId

string

The identifier of the refresh request. Provide this identifier in all service requests.
serviceExceptionJson

string

Failure error code in JSON format (empty if no error)
startTime

string (date-time)

The start date and time of the refresh in UTC format.
status

string

  • Unknown if the completion state is unknown or a refresh is in progress.
  • Completed for a successfully completed refresh.
  • Failed for an unsuccessful refresh (serviceExceptionJson will contain the error code).
  • Disabled if the refresh is disabled by a selective refresh.

Refreshable

Object

A Power BI refreshable is a dataset that's been refreshed at least once, or for which a valid refresh schedule exists. If a dataset doesn't meet either of these conditions, then it won't show up in the API response. Power BI retains a seven-day refresh history for each dataset, up to a maximum of sixty refreshes.

Name Type Description
averageDuration

number

The average duration in seconds of a refresh during the time window for which refresh data exists
capacity

Capacity

The capacity for the refreshable item
configuredBy

string[]

The refreshable owners
endTime

string (date-time)

The end time of the window for which refresh data exists in UTC format.
group

RefreshableGroup

The associated group for the refreshable item
id

string

The object ID of the refreshable
kind

RefreshableKind

The refreshable kind
lastRefresh

Refresh

The last Power BI refresh history entry for the refreshable item
medianDuration

number

The median duration in seconds of a refresh within the time window for which refresh data exists
name

string

The display name of the refreshable
refreshCount

integer

The number of refreshes within the time window for which refresh data exists
refreshFailures

integer

The number of refresh failures within the time window for which refresh data exists
refreshSchedule

RefreshSchedule

The refresh schedule for the refreshable item
refreshesPerDay

integer

The number of refreshes per day (scheduled and on-demand) within the time window for which refresh data exists
startTime

string (date-time)

The start time of the window for which refresh data exists in UTC format.

RefreshableGroup

Object

A Power BI group associated to a Refreshable item

Name Type Description
id

string (uuid)

The workspace ID
name

string

The group name

RefreshableKind

Enumeration

The refreshable kind

Value Description
Dataset

Dataset

Refreshables

Object

A Power BI refreshables list

Name Type Description
@odata.context

string

OData context
value

Refreshable[]

The refreshables

RefreshAttempt

Object

Power BI automatically makes multiple attempts to refresh a dataset if it experiences a refresh failure. This object contains information about each refresh attempt.

Name Type Description
attemptId

integer

The index of the refresh attempt.
endTime

string (date-time)

The end date and time of the refresh attempt. The value is void if the refresh attempt is in progress.
serviceExceptionJson

string

Failure error code in JSON format. Void if there's no error.
startTime

string (date-time)

The start date and time of the refresh attempt.
type

RefreshAttemptType

The type of refresh attempt.

RefreshAttemptType

Enumeration

The type of refresh attempt.

Value Description
Data

The refresh attempt to load data into the dataset.
Query

The attempt to refresh premium query caches and dashboard tiles.u

RefreshSchedule

Object

A Power BI refresh schedule for imported model

Name Type Description
days

days[]

The days on which to execute the refresh
enabled

boolean

Whether the refresh is enabled
localTimeZoneId

string

The ID of the time zone to use. For more information, see Time zone info.
notifyOption

ScheduleNotifyOption

The notification option on termination of a scheduled refresh. Service principals only support the NoNotification value.
times

string[]

The times of day to execute the refresh

RefreshType

Enumeration

The type of refresh request

Value Description
OnDemand

The refresh was triggered interactively through the Power BI portal
OnDemandTraining

The refresh was triggered interactively through the Power BI portal with automatic aggregations training
Scheduled

The refresh was triggered by a dataset refresh schedule setting
ViaApi

The refresh was triggered by an API call
ViaEnhancedApi

The refresh was triggered by an enhanced refresh REST API call
ViaXmlaEndpoint

The refresh was triggered through Power BI public XMLA endpoint

ScheduleNotifyOption

Enumeration

The notification option on termination of a scheduled refresh. Service principals only support the NoNotification value.

Value Description
MailOnFailure

A mail notification will be sent on refresh failure
NoNotification

No notification will be sent

TenantKey

Object

Encryption key information

Name Type Description
createdAt

string (date-time)

The creation date and time of the encryption key
id

string (uuid)

The ID of the encryption key
isDefault

boolean

Whether the encryption key is the default key for the entire tenant. Any newly created capacity inherits the default key.
keyVaultKeyIdentifier

string

The URI that uniquely specifies the encryption key in Azure Key Vault
name

string

The name of the encryption key
updatedAt

string (date-time)

The last update date and time of the encryption key