使用 Reporting Services 的 REST API 進行開發Develop with the REST APIs for Reporting Services

本主題適用於:THIS TOPIC APPLIES TO: 是SQL Server Reporting Services (2017 和更新版本)SQL Server Reporting Services (2017 and later) 否Power BI 報表伺服器Power BI Report Server本主題適用於:THIS TOPIC APPLIES TO: 是SQL Server Reporting Services (2017 和更新版本)SQL Server Reporting Services (2017 and later) 否Power BI 報表伺服器Power BI Report Server

Microsoft SQL Server 2017 Reporting Services 支援具象狀態傳輸 (REST) API。Microsoft SQL Server 2017 Reporting Services 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 可透過程式設計方式存取 SQL Server 2017 Reporting Services 報表伺服器目錄中的物件。The REST API provides programmatic access to the objects in a SQL Server 2017 Reporting Services 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.

注意

如果您想要檢視或刪除個人資料,請檢閱 GDPR 的 Windows 資料主體要求網站中的 Microsoft 指引。If you’re interested in viewing or deleting personal data, please review Microsoft's guidance in the Windows Data Subject Requests for the GDPR site. 如果您想要尋找 GDPR 的一般資訊,請參閱服務信任入口網站的 GDPR 一節If you’re looking for general information about GDPR, see the GDPR section of the Service Trust portal.

REST API 要求/回應的元件Components of a REST API request/response

REST API 要求/回應配對可分成五個元件:A REST API request/response pair can be separated into five components:

  • {URI-scheme} :// {URI-host} / {resource-path} ? {query-string} 所組成的要求 URIThe 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 作業,也必須在 Content-type 要求標頭中指定主體的 MIME 編碼類型。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

新式 REST API 需要新式 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 是可攔截 REST 要求的免費 Web 偵錯 Proxy,讓您輕鬆就能診斷 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 為建置基礎的 HTML5 應用程式,以及 PowerShell 範例。The sample includes an HTML5 app built on TypeScript, React, and webpack along with a PowerShell example.

更多問題嗎?More questions? 請嘗試詢問 Reporting Services 論壇Try asking the Reporting Services forum