使用适用于 Power BI 报表服务器的 REST API 进行开发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. 对象的示例包括文件夹、报表、KPI、数据源、数据集、刷新计划、订阅等。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 API 请求/响应的组件Components 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. 例如 httphttpsFor example, http or https.
    • URI 主机:指定托管 REST 服务终结点的服务器的域名或 IP 地址,如 myserver.contoso.comURI 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. Reporting Services REST API 支持 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/jsonSome 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.

API 文档API documentation

对于现代 API 文档,需要现代的 REST 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.

测试 API 调用Testing API calls

用于测试 HTTP 请求/响应消息的一种工具是 FiddlerA tool for testing HTTP request/response messages is Fiddler. Fiddler 是一个免费的 Web 调试代理,可以截获 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

SwaggerHub 上查看可用的 API。Review the available APIs over on SwaggerHub.

示例可在 GitHub 上找到。Samples are available on GitHub. 此示例包含基于 TypeScript、React、Webpack 和 PowerShell 示例构建的 HTML5 应用。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