Разработка с помощью интерфейсов REST API для решения "Сервер отчетов Power BI"Develop with the REST APIs for Power BI Report Server

Решение "Сервер отчетов Power BI" поддерживает интерфейсы REST API.Power BI Report Server support Representational State Transfer (REST) APIs. Интерфейсы REST API — это конечные точки служб, которые поддерживают набор операций HTTP (методов) и предоставляют ресурсам на сервере отчетов доступ на создание, получение, обновление или удаление.The REST APIs are service endpoints that support a set of HTTP operations (methods), which provide create, retrieve, update, or delete access for resources within a report server.

REST API обеспечивает программный доступ к объектам в каталоге решения "Сервер отчетов Power BI".The REST API provides programmatic access to the objects in a Power BI Report Server catalog. Такими объектами могут быть папки, отчеты, ключевые показатели эффективности, источники данных, наборы данных, планы обновления, подписки и др.Examples of objects are folders, reports, KPIs, data sources, datasets, refresh plans, subscriptions, and more. С помощью REST API вы можете, например, перемещаться по иерархии папок, обнаруживать содержимое папки или скачивать определение отчета.Using the REST API, you can, for example, navigate the folder hierarchy, discover the contents of a folder, or download a report definition. Вы также можете создавать, обновлять и удалять объекты.You can also create, update, and delete objects. Примеры операций с объектами: отправка отчета, выполнение плана обновления, удаление папки и т. д.Examples of working with objects are upload a report, execute a refresh plan, delete a folder, and so on.

Компоненты запросов и ответов REST APIComponents of a REST API request/response

Пару "запрос — ответ" REST API можно разделить на пять компонентов:A REST API request/response pair can be separated into five components:

  • URI запроса{URI-scheme} :// {URI-host} / {resource-path} ? {query-string}.The request URI, which consists of: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Хотя URI запроса содержится в заголовке сообщения запроса, в нашем случае мы вызываем его отдельно, так как для большинства языков или платформ требуется передавать его отдельно от сообщения запроса.Although the request URI is included in the request message header, we call it out separately here because most languages or frameworks require you to pass it separately from the request message.

    • Схема URI — определяет протокол, используемый для передачи запроса.URI scheme: Indicates the protocol used to transmit the request. Например, http или https.For example, http or https.
    • Узел URI — определяет доменное имя или IP-адрес сервера, на котором размещена конечная точка службы REST, например myserver.contoso.com.URI host: Specifies the domain name or IP address of the server where the REST service endpoint is hosted, such as myserver.contoso.com.
    • Путь к ресурсу — определяет ресурс или коллекцию ресурсов, которые могут содержать несколько сегментов, используемых службой при определении выбора этих ресурсов.Resource path: Specifies the resource or resource collection, which may include multiple segments used by the service in determining the selection of those resources. Например, CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties может использоваться для получения указанных свойств для класса CatalogItem.For example: CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties can be used to get the specified properties for the CatalogItem.
    • Строка запроса (необязательно) — предоставляет дополнительные простые параметры, такие как критерий выбора версии API или ресурсов.Query string (optional): Provides additional simple parameters, such as the API version or resource selection criteria.
  • Поля заголовка сообщения HTTP-запроса:HTTP request message header fields:

    • Обязательный метод HTTP (операция или команда), который сообщает службе тип запрашиваемой операции.A required HTTP method (also known as an operation or verb), which tells the service what type of operation you are requesting. Интерфейсы REST API служб Reporting Services поддерживают такие методы: DELETE, GET, HEAD, PUT, POST и PATCH.Reporting Services REST APIs support DELETE, GET, HEAD, PUT, POST, and PATCH methods.
    • Необязательные дополнительные поля заголовка, требуемые для указанного URI и метода HTTP.Optional additional header fields, as required by the specified URI and HTTP method.
  • Необязательные поля текста сообщения HTTP-запроса для поддержки URI и операции HTTP.Optional HTTP request message body fields, to support the URI and HTTP operation. Например, операции POST содержат объекты в кодировке MIME, которые передаются в виде сложных параметров.For example, POST operations contain MIME-encoded objects that are passed as complex parameters. Для операций POST или PUT тип кодировки MIME для текста сообщения также должен быть указан в заголовке запроса Content-type.For POST or PUT operations, the MIME-encoding type for the body should be specified in the Content-type request header as well. Для некоторых служб требуется использовать определенный тип MIME, например application/json.Some services require you to use a specific MIME type, such as application/json.
  • Поля заголовка сообщения HTTP-ответа:HTTP response message header fields:

    • Код состояния HTTP — от кодов успешного завершения 2xx до кодов ошибок 4xx или 5xx.An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes. Кроме того, может возвращаться определяемый службой код состояния, как указано в документации по API.Alternatively, a service-defined status code may be returned, as indicated in the API documentation.
    • Необязательные дополнительные поля заголовка, требуемые для поддержки ответа на запрос, например заголовок ответа Content-type.Optional additional header fields, as required to support the request's response, such as a Content-type response header.
  • Необязательные поля текста сообщения HTTP-ответа:Optional HTTP response message body fields:

    • В тексте HTTP-ответа возвращаются объекты в кодировке MIME, например ответа метода GET, который возвращает данные.MIME-encoded response objects are returned in the HTTP response body, such as a response from a GET method that is returning data. Как правило, эти объекты возвращаются в структурированном формате, например JSON или XML, как указано в заголовок ответа Content-type.Typically, these objects are returned in a structured format such as JSON or XML, as indicated by the Content-type response header.

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

Современные REST API описаны в современной документации по API.A modern REST API calls for modern API documentation. REST API основан на спецификации OpenAPI (она же спецификация Swagger).The REST API is built on the OpenAPI specification (a.k.a. Документацию по этой спецификации см. на сайте SwaggerHub.the swagger specification) and documentation is available on SwaggerHub. Кроме размещения документации по API, сайт SwaggerHub позволяет создать клиентскую библиотеку на любом языке: JavaScript, TypeScript, C#, Java, Python, Ruby и др.Beyond documenting the API, SwaggerHub helps generate a client library in the language of choice – JavaScript, TypeScript, C#, Java, Python, Ruby, and more.

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

Для тестирования HTTP-запросов и ответов используется средство Fiddler.A tool for testing HTTP request/response messages is Fiddler. Это бесплатный веб-прокси для отладки, который может перехватывать запросы REST, упрощая диагностику сообщений HTTP-запросов и ответов.Fiddler is a free web debugging proxy that can intercept your REST requests, making it easy to diagnose the HTTP request/ response messages.

Дальнейшие действияNext steps

Просмотр доступных интерфейсов API на сайте SwaggerHub.Review the available APIs over on SwaggerHub.

Примеры доступны на сайте GitHub.Samples are available on GitHub. Примеры включают приложение HTML5, созданное с помощью TypeScript, React и Webpack, а также пример PowerShell.The sample includes an HTML5 app built on TypeScript, React, and webpack along with a PowerShell example.

Появились дополнительные вопросы?More questions? Попробуйте задать вопрос в сообществе Power BI.Try asking the Power BI Community