Sviluppare con le API REST per un server di report di Power BIDevelop with the REST APIs for Power BI Report Server

Il server di report di Power BI supporta le API REST (Representational State Transfer, Trasferimento di stato rappresentativo).Power BI Report Server support Representational State Transfer (REST) APIs. Le API REST sono endpoint servizio che supportano un set di operazioni HTTP (metodi) che offrono l'accesso per le operazioni di creazione, recupero, aggiornamento o eliminazione per le risorse in un server di report.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.

L'API REST offre l'accesso a livello di codice agli oggetti contenuti in un catalogo del server di report di Power BI.The REST API provides programmatic access to the objects in a Power BI Report Server catalog. Gli oggetti sono, ad esempio, cartelle, report, KPI, origini dati, set di dati, piani di aggiornamento, sottoscrizioni e altri ancora.Examples of objects are folders, reports, KPIs, data sources, datasets, refresh plans, subscriptions, and more. Le API REST consentono di esplorare la gerarchia delle cartelle, individuare il contenuto di una cartella o di scaricare una definizione del report.Using the REST API, you can, for example, navigate the folder hierarchy, discover the contents of a folder, or download a report definition. È anche possibile creare, aggiornare ed eliminare gli oggetti.You can also create, update, and delete objects. Le operazioni che si possono eseguire con gli oggetti sono ad esempio caricare un report, eseguire un piano di aggiornamento, eliminare una cartella e così via.Examples of working with objects are upload a report, execute a refresh plan, delete a folder, and so on.

Componenti di una richiesta/risposta dell'API RESTComponents of a REST API request/response

Una coppia richiesta/risposta dell'API REST può essere suddivisa in cinque componenti:A REST API request/response pair can be separated into five components:

  • URI della richiesta, costituito da: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}.The request URI, which consists of: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Sebbene l'URI della richiesta sia incluso nell'intestazione del messaggio di richiesta, viene evidenziato separatamente perché la maggior parte dei linguaggi o framework richiede di passarlo separatamente dal messaggio di richiesta.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.

    • Schema URI: indica il protocollo usato per trasmettere la richiesta.URI scheme: Indicates the protocol used to transmit the request. Ad esempio: http o https.For example, http or https.
    • Host URI: specifica il nome di dominio o l'indirizzo IP del server in cui è ospitato l'endpoint servizio REST, ad esempio 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.
    • Percorso risorsa: specifica la risorsa o la raccolta di risorse, che può includere più segmenti usati dal servizio per determinare la selezione di tali risorse.Resource path: Specifies the resource or resource collection, which may include multiple segments used by the service in determining the selection of those resources. Ad esempio: è possibile usare CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties per recuperare le proprietà specificate per CatalogItem.For example: CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties can be used to get the specified properties for the CatalogItem.
    • Stringa di query (facoltativa): offre parametri semplici aggiuntivi, ad esempio la versione API o i criteri di selezione delle risorse.Query string (optional): Provides additional simple parameters, such as the API version or resource selection criteria.
  • Campi dell'intestazione del messaggio della richiesta HTTP:HTTP request message header fields:

    • Metodo HTTP obbligatorio (noto anche come operazione o verbo) che comunica al servizio il tipo di operazione richiesta.A required HTTP method (also known as an operation or verb), which tells the service what type of operation you are requesting. Le API REST di Reporting Services supportano i metodi DELETE, GET, HEAD, PUT, POST e PATCH.Reporting Services REST APIs support DELETE, GET, HEAD, PUT, POST, and PATCH methods.
    • Campi dell'intestazione aggiuntivi facoltativi, come richiesto dal metodo HTTP e dall'URI specificati.Optional additional header fields, as required by the specified URI and HTTP method.
  • Campi del corpo del messaggio di richiesta HTTP facoltativi, per supportare l'operazione HTTP e l'URI.Optional HTTP request message body fields, to support the URI and HTTP operation. Ad esempio, le operazioni POST contengono oggetti con codifica MIME passati come parametri complessi.For example, POST operations contain MIME-encoded objects that are passed as complex parameters. Per le operazioni POST o PUT, è necessario specificare anche il tipo di codifica MIME per il corpo nell'intestazione della richiesta 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. Alcuni servizi richiedono di usare un tipo MIME specifico, come application/json.Some services require you to use a specific MIME type, such as application/json.
  • Campi dell'intestazione del messaggio della risposta HTTP:HTTP response message header fields:

    • Codice di stato HTTP, compreso tra 2xx per le operazioni riuscite e 4xx o 5xx per le operazioni con errori.An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes. In alternativa, può essere restituito un codice di stato definito dal servizio, come indicato nella documentazione dell'API.Alternatively, a service-defined status code may be returned, as indicated in the API documentation.
    • Campi dell'intestazione aggiuntivi facoltativi, per il supporto della risposta della richiesta, ad esempio un'intestazione della risposta Content-type.Optional additional header fields, as required to support the request's response, such as a Content-type response header.
  • Campi del corpo del messaggio di risposta HTTP facoltativi:Optional HTTP response message body fields:

    • Gli oggetti della risposta con codifica MIME sono restituiti nel corpo della risposta HTTP, ad esempio una risposta da un metodo GET che restituisce dati.MIME-encoded response objects are returned in the HTTP response body, such as a response from a GET method that is returning data. In genere questi oggetti vengono restituiti in un formato strutturato, come JSON o XML, come indicato dall'intestazione della risposta Content-type.Typically, these objects are returned in a structured format such as JSON or XML, as indicated by the Content-type response header.

Documentazione dell'APIAPI documentation

Un'API REST moderna richiede una documentazione API moderna.A modern REST API calls for modern API documentation. L'API REST è basata sulla specifica OpenAPI, ovveroThe REST API is built on the OpenAPI specification (a.k.a. la specifica Swagger, e la documentazione è disponibile in SwaggerHub.the swagger specification) and documentation is available on SwaggerHub. Oltre a fornire la documentazione per l'API, SwaggerHub consente di generare una libreria client nel linguaggio scelto, ad esempio JavaScript, TypeScript, C#, Java, Python, Ruby e altri ancora.Beyond documenting the API, SwaggerHub helps generate a client library in the language of choice – JavaScript, TypeScript, C#, Java, Python, Ruby, and more.

Test delle chiamate APITesting API calls

Fiddler è uno strumento che permette di testare i messaggi di richiesta/risposta HTTP.A tool for testing HTTP request/response messages is Fiddler. Fiddler è un proxy di debug Web gratuito che intercetta le richieste REST semplificando così la diagnosi dei messaggi di richiesta/risposta HTTP.Fiddler is a free web debugging proxy that can intercept your REST requests, making it easy to diagnose the HTTP request/ response messages.

Passaggi successiviNext steps

Rivedere le API disponibili in SwaggerHub.Review the available APIs over on SwaggerHub.

Gli esempi sono disponibili in GitHub.Samples are available on GitHub. L'esempio include un'app HTML5 basata su TypeScript, React e webpack, oltre a un esempio PowerShell.The sample includes an HTML5 app built on TypeScript, React, and webpack along with a PowerShell example.

Altre domande?More questions? Provare a rivolgersi alla community di Power BITry asking the Power BI Community