使用 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 主機:指定網域名稱或伺服器的 IP 位址,在其中裝載 REST 服務端點,例如 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:

    • MIME 編碼回應物件會在 HTTP 回應本文中傳回,例如來自 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 規格 (也稱為The REST API is built on the OpenAPI specification (a.k.a. swagger 規格),文件可於 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 偵錯 Proxy,可以攔截 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