Sviluppare con le API REST per Server di report di Power BI

Server di report di Power BI supportano le API REST (Representational State Transfer). Le API REST sono endpoint di servizio che supportano un set di operazioni HTTP (metodi) che offrono l'accesso con diritti di creazione, recupero, aggiornamento o eliminazione per le risorse contenute in un server di report.

L'API REST fornisce l'accesso a livello di codice agli oggetti in un catalogo Server di report di Power BI. Esempi di oggetti sono cartelle, report, indicatori KPI, origini dati, set di dati, piani di aggiornamento, sottoscrizioni e così via. Tramite l'API REST è ad esempio possibile esplorare la gerarchia di cartelle, individuare il contenuto di una cartella o scaricare la definizione di un report. È anche possibile creare, aggiornare ed eliminare oggetti. Esempi di attività che è possibile eseguire sugli oggetti includono il caricamento di un report, l'esecuzione di un piano di aggiornamento, l'eliminazione di una cartella e così via.

Nota

Se si vuole visualizzare o eliminare dati personali, consultare il materiale sussidiario di Microsoft sul sito Richieste del soggetto dei dati per l'RGPD in Windows. Se si cercano le informazioni generali sull'RGPD, vedere la sezione sull'RGPD del portale del servizio attendibile.

Componenti della richiesta-risposta di un'API REST

La coppia richiesta-risposta di un'API REST può essere suddivisa in cinque componenti:

  • L'URI della richiesta, costituito da: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Anche se l'URI della richiesta è incluso nell'intestazione del messaggio di richiesta, viene qui considerato come elemento distinto perché la maggior parte dei linguaggi o dei framework richiede di passarlo separatamente dal messaggio di richiesta.

    • Schema URI: indica il protocollo usato per trasmettere la richiesta. Ad esempio, http o https.
    • Host dell'URI: specifica il nome di dominio o l'indirizzo IP del server in cui l'endpoint del servizio REST è ospitato, ad esempio myserver.contoso.com.
    • Percorso della risorsa: specifica la risorsa o la raccolta di risorse che può includere più segmenti usati dal servizio per determinare la selezione di queste risorse. Ad esempio: CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties può essere usato per ottenere le proprietà specificate per CatalogItem.
    • Stringa di query (facoltativo): fornisce parametri semplici aggiuntivi, ad esempio la versione dell'API o i criteri di selezione delle risorse.
  • Campi di intestazione del messaggio di richiesta HTTP:

    • Un metodo HTTP necessario (noto anche come operazione o verbo) che indica al servizio il tipo di operazione richiesto. Le API REST di Reporting Services supportano i metodi DELETE, GET, HEAD, PUT, POST e PATCH.
    • Campi di intestazione aggiuntivi facoltativi, come richiesto dall'URI e dal metodo HTTP specificati.
  • Campi facoltativi del corpo del messaggio di richiesta HTTP per supportare l'operazione URI e HTTP. Le operazioni POST contengono ad esempio oggetti con codifica MIME che vengono passati come parametri complessi. Per le operazioni POST o PUT, il tipo di codifica MIME per il corpo deve essere specificato anche nell'intestazione della richiesta Content-type. Alcuni servizi richiedono l'uso di un tipo MIME specifico, ad esempio application/json.

  • Campi di intestazione del messaggio di risposta HTTP:

    • Un codice di stato HTTP, compreso tra codici di riuscita 2xx e codici di errore 4xx o 5xx. In alternativa, può essere restituito un codice di stato definito dal servizio, come indicato nella documentazione dell'API.
    • Campi di intestazione aggiuntivi facoltativi eventualmente necessari per supportare la risposta della richiesta, ad esempio un'intestazione della risposta Content-type.
  • Campi facoltativi del corpo del messaggio di risposta HTTP:

    • Gli oggetti della risposta con codifica MIME vengono restituiti nel corpo della risposta HTTP, ad esempio una risposta da un metodo GET che restituisce dati. In genere, questi oggetti vengono restituiti in un formato strutturato, ad esempio JSON o XML, come indicato dall'intestazione della risposta Content-type.

Documentazione sull'API

Un'API REST moderna richiede una documentazione moderna. L'API REST è basata sulla specifica OpenAPI (ad esempio la specifica swagger) e la documentazione è disponibile in Microsoft Learn.

Test delle chiamate API

Uno strumento per testare i messaggi di richiesta-risposta HTTP è Fiddler. Fiddler è un proxy di debug Web gratuito in grado di intercettare le richieste REST, semplificando la diagnosi dei messaggi di richiesta-risposta HTTP.

Esaminare le API disponibili in Microsoft Learn.

Esempi sono disponibili in GitHub. L'esempio include un'app HTML5 basata su TypeScript, React e webpack insieme a un esempio di PowerShell.

Altre domande? Contattare la community di Power BI