Che cosa sono le API REST per Reporting Services?

  • Articolo

Si applica a: SQL Server Reporting Services (2017 e versioni successive) ❌ Server di report di Power BI

Microsoft SQL Server 2017 Reporting Services supporta le API REST (Representational State Transfer, trasferimento di stato rappresentativo). Le API REST sono endpoint di servizio che supportano set di operazioni (metodi) HTTP. Questi metodi consentono di creare, recuperare, aggiornare o eliminare l'accesso per le risorse all'interno di un server di report.

Le API REST forniscono accesso programmatico agli oggetti contenuti in un catalogo del server di report di SQL Server 2017 Reporting Services. Ecco alcuni esempi di oggetti:

  • Cartelle
  • Report
  • Indicatori KPI
  • Origini dati
  • Set di dati
  • Piani di aggiornamento
  • Sottoscrizioni

Tramite le API REST è 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.

Nota

Se si vogliono visualizzare o eliminare dati personali, vedere le indicazioni offerte da Microsoft nel documento sulle richieste del soggetto dei dati Windows nel sito relativo al regolamento GDPR. Per informazioni generali sul regolamento GDPR, vedere la sezione su GDPR in Service Trust Portal.

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:

    • Anche se l'URI della richiesta è incluso nell'intestazione del messaggio di richiesta, la maggior parte dei linguaggi o dei framework richiede di passarlo separatamente dal messaggio di richiesta.
    • È costituito da {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}.
    URI della richiesta Descrizione
    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.
    Resource path 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 è possibile usare CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties per ottenere le proprietà specificate per CatalogItem.
    Stringa di query (facoltativo) Fornisce parametri più semplici, ad esempio la versione dell'API o i criteri di selezione delle risorse.

  • Campi di intestazione del messaggio di richiesta HTTP:

    • Un metodo HTTP obbligatorio, noto anche come operazione o verbo.
    • Indica al servizio il tipo di operazione richiesta in quel momento. 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:

    • Supporta l'URI e l'operazione HTTP. Le operazioni POST contengono ad esempio oggetti con codifica Multipurpose Internet Mail Extensions (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. Un'API REST è basata sulla specifica OpenAPI, detta anche specifica swagger. La documentazione delle API REST del server di report di Power BI è disponibile su Microsoft Learn.

Test delle chiamate API

In caso di necessità di uno strumento che testi i messaggi di richiesta-risposta HTTP, Fiddler è un proxy di debug Web gratuito in grado di intercettare le richieste REST, semplificando la diagnosi dei messaggi di richiesta-risposta HTTP.

Contenuto correlato