Разработка с помощью REST API для Сервер отчетов Power BI

Сервер отчетов Power BI поддерживают API передачи репрезентативного состояния (REST). API-интерфейсы REST — это конечные точки службы, которые поддерживают набор операций HTTP (методов), предоставляющих доступ на создание, получение, обновление или удаление ресурсов в сервере отчетов.

REST API предоставляет программный доступ к объектам в каталоге Сервер отчетов Power BI. Примерами объектов являются папки, отчеты, ключевые показатели эффективности, источники данных, наборы данных, планы обновления, подписки и многое другое. С помощью API REST можно, например, перемещаться по иерархии папок, обнаруживать содержимое папки или загружать определение отчета. Можно также создавать, обновлять и удалять объекты. Примерами работы с объектами являются отправка отчета, выполнение плана обновления, удаление папки и т. д.

Компоненты запроса и ответа API REST

Пару запроса-ответа API REST можно разделить на пять компонентов:

• URI запроса, который состоит из: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Несмотря на то, что URI запроса включается в заголовок сообщения запроса, мы выделяем его отдельно, так как большинство языков или платформ требуют передавать его отдельно от сообщения запроса.

  • Схема URI: указывает протокол, используемый для передачи запроса. Например, http или https.
  • Узел URI: указывает имя домена или IP-адрес сервера, где размещена конечная точка службы REST, например myserver.contoso.com.
  • Путь к ресурсу: указывает ресурс или коллекцию ресурсов, которые могут содержать несколько сегментов, используемых службой для определения выборки этих ресурсов. Например: для получения указанных свойств CatalogItem можно использовать CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties.
  • Строка запроса (необязательно): предоставляет дополнительные простые параметры, такие как критерий выбора ресурса или версии API.

• Поля заголовка сообщения HTTP-запроса:

  • Обязательный метод HTTP (также известный как операция или команда), который сообщает службе, какой тип операции запрашивается. API-интерфейсы REST служб Reporting Services поддерживают методы DELETE, GET, HEAD, PUT, POST и PATCH.
  • Необязательные дополнительные поля заголовка, требуемые для указанного URI и метода HTTP.

• Необязательные поля текста сообщения запроса HTTP для поддержки URI и операции HTTP. Например, операции POST содержат объекты в кодировке MIME, которые передаются как сложные параметры. Для операций POST или PUT тип в кодировке MIME текста должен быть указан в заголовке запроса Content-type. Для некоторых служб необходимо использовать конкретный тип MIME, например application/json.

• Поля заголовка сообщения ответа HTTP:

  • Код состояния HTTP— от кодов успешного выполнения 2xx до кодов ошибок 4xx или 5xx. Кроме того, может быть возвращен определяемый службой код состояния, как указано в документации по API.
  • Необязательные дополнительные поля заголовка, как требуется для поддержки ответа запроса, такие как заголовок ответа Content-type.

• Необязательные поля текста сообщения ответа HTTP:

  • В тексте ответа HTTP возвращаются объекты ответа в кодировке MIME, например ответ от метода GET, который возвращает данные. Как правило, эти объекты возвращаются в структурированном виде, например JSON или XML, как указано в заголовке ответа Content-type.

Документация по API

Современный API REST требуется для современного документирования API. REST API основан на спецификации OpenAPI (a.k.a. спецификации swagger) и документация доступна в Microsoft Learn.

Тестирование вызовов API

Для тестирования сообщений запросов и ответов HTTP используется средство Fiddler. Fiddler — это бесплатный прокси-сервер веб-отладки, который может перехватывать запросы REST, что упрощает диагностику сообщений запросов и ответов HTTP.

Связанный контент

Просмотрите доступные API в Microsoft Learn.

Образцы можно найти на сайте GitHub. Образец включает в себя приложение HTML5, созданное на TypeScript, React и webpack с примером PowerShell.

Есть еще вопросы? Задайте их в сообществе Power BI.