Condividi tramite

Paradigma di accesso programmatico

Questo diagramma mostra il modello di chiamata API usato per creare un nuovo modello di report, pianificare il report personalizzato e recuperare i dati sugli errori.

Flusso di alto livello Figura 1: Flusso di alto livello del modello di chiamata API

Questo elenco fornisce altri dettagli sulla figura 1.

  1. L'applicazione client può definire un modello/schema di report personalizzato chiamando l'API di creazione query per il report . In alternativa, è possibile selezionare un modello di report (QueryId) dagli esempi di libreria dei modelli di report in Elenco di query di sistema per l'accesso programmatico alle informazioni dettagliate dei partner.
  2. In caso di esito positivo, l'API Crea query report restituisce QueryId.
  3. L'applicazione client deve quindi chiamare l'API Crea report utilizzando QueryId insieme alla data di inizio del report, all'intervallo di ripetizione, alla ricorrenza e a un URI di callback facoltativo.
  4. In caso di esito positivo, l'API Crea report restituisce ReportId.
  5. L'applicazione client riceve una notifica all'URL di callback non appena i dati del report sono pronti per il download.
  6. L'applicazione client utilizza quindi l'API Get Report Executions per eseguire una query sullo stato del report con l'ID report e l'intervallo di date.
  7. In caso di esito positivo, viene restituito il collegamento di download del report e l'applicazione può avviare il download dei dati.

Specifiche del linguaggio di query del report

Sebbene forniamo query di sistema che è possibile utilizzare per creare report, è anche possibile creare query personalizzate in base alle esigenze aziendali. Per altre informazioni sulle query personalizzate, vedere Specifica delle query personalizzate.

Creare un'API per le query di report

L'API consente di creare query personalizzate che definiscono il set di dati da cui è necessario esportare le colonne e le metriche. L'API offre la flessibilità necessaria per creare un nuovo modello di report in base alle esigenze aziendali.

È anche possibile usare le query di sistema fornite. Quando i modelli di report personalizzati non sono necessari, è possibile chiamare direttamente l'API Create Report usando i QueryIds delle query di sistema fornite.

L'esempio seguente illustra come creare una query personalizzata per ottenere i primi 10 clienti in base ai ricavi del mese precedente.

Sintassi della richiesta

Metodo URI della richiesta
INSERISCI https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledQueries

Header di richiesta

Intestazione TIPO Descrizione
Autorizzazione corda Obbligatorio. Token di accesso Microsoft Entra. Il formato è Bearer <token>.
Tipo di Contenuto corda Application/JSON

Parametro del percorso

Nessuno

Query parameter (Parametro di query)

Nessuno

Payload della richiesta di esempio

{
  "Name": "CustomersRevenueQuery",
  "Description": "Query to get top 10 customers by revenue for last month",
  "Query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH"
}

Glossario delle richieste

Questa tabella fornisce le definizioni chiave degli elementi nel payload della richiesta.

Parametro Obbligatorio Descrizione Valori consentiti
Nome Sì Nome descrittivo della query corda
Descrizione NO Descrizione di ciò che la query restituisce corda
Quesito Sì Stringa di query del report Tipo di dati: stringa
Query personalizzata in base alle esigenze aziendali

Annotazioni

Per esempi di query personalizzate, vedere Esempi di query di esempio.

Risposta di esempio

Il payload della risposta è strutturato come segue:

Codici di risposta: 200, 400, 401, 403, 500

Esempio di payload della risposta:

{
  "value": [
    {
      "queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
      "name": "CustomersRevenueQuery",
      "description": "Query to get top 10 customers by revenue for last month",
      "query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
      "type": "userDefined",
      "user": "GAUser@PITEST2.onmicrosoft.com",
      "createdTime": "2021-03-30T12:52:39Z"
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": "Query created successfully",
  "statusCode": 200,
  "dataRedacted": false
}

Glossario della risposta

Questa tabella fornisce le definizioni chiave degli elementi nel payload della richiesta.

Parametro Descrizione
QueryId Identificatore univoco universale (UUID) della query creata
Nome Nome descrittivo assegnato alla query nel payload della richiesta
Descrizione Descrizione specificata durante la creazione della query
Quesito Query del report passata come input durante la creazione della query
TIPO Impostare su userDefined
Utente ID utente utilizzato per la creazione della query
CreatedTime Ora UTC in cui la query è stata creata in questo formato: aaaa-MM-ggTHH:mm:ssZ
Conteggio totale Numero di set di dati nella matrice Valore
StatusCode Codice risultato
I valori possibili sono 200, 400, 401, 403, 500
Messaggio Messaggio di stato dall'esecuzione dell'API

API per la creazione di report

Dopo aver creato correttamente un modello di report personalizzato e aver ricevuto il QueryID come parte della risposta Create Report Query , questa API può essere chiamata per pianificare l'esecuzione di una query a intervalli regolari. È possibile impostare una frequenza e una pianificazione per il report da recapitare. Per le query di sistema fornite, è anche possibile chiamare l'API Crea report con QueryId.

Callback URL (URL di richiamata)

L'API di creazione del report accetta un URL di callback. Questo URL verrà chiamato una volta che la generazione del report è riuscita. L'URL di richiamata deve essere raggiungibile pubblicamente. Oltre all'URL, può essere fornito anche un metodo di callback. Il metodo di callback può essere GET solo o POST. Il metodo predefinito, se non viene passato alcun valore, sarà POST. Il reportId che ha completato la generazione verrà sempre passato di nuovo durante il callback.

Callback POST: Se l'URL passato è stato https://www.contosso.com/callback, l'URL richiamato sarà https://www.contosso.com/callback/<reportID>

GET callback: se l'URL passato è stato https://www.contosso.com/callback, l'URL richiamato sarà https://www.contosso.com/callback?reportId=<reportID>

Rapporti ExecuteNow

È prevista la generazione di un report senza pianificazione. Il payload API di creazione del report può accettare un parametro ExecuteNow, che accoderà il report da generare non appena l'API viene chiamata. Quando ExecuteNow è impostato su true, i campi: StartTime, RecurrenceCount, RecurrenceInterval vengono ignorati perché questi report non sono pianificati.

È possibile passare due campi aggiuntivi quando ExecuteNow è true QueryStartTime e QueryEndTime. Questi due campi sostituiranno il TIMESPAN campo nella query. Questi campi non sono applicabili ai report pianificati in quanto i dati verranno generati continuamente per un periodo di tempo fisso che non cambia.

Sintassi della richiesta

Metodo URI della richiesta
INSERISCI https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport

Header di richiesta

Intestazione TIPO Descrizione
Autorizzazione corda Obbligatorio. Token di accesso Microsoft Entra. Il formato è Bearer <token>.
Tipo di Contenuto corda Application/JSON

Parametro percorso

Nessuno

Parametro query

Nessuno

Payload della richiesta di esempio

{
  "ReportName": "Top10_CustomersReport",
  "Description": "Top 10 customers by revenue for last month",
  "QueryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
  "StartTime": "2021-03-31T18:41:00Z",
  "ExecuteNow": false,
  "QueryStartTime": null,
  "QueryEndTime": null,
  "RecurrenceInterval": 24,
  "RecurrenceCount": 100,
  "Format": "CSV",
  "CallbackUrl": "https://<SampleCallbackUrl>",
  "CallbackMethod": "GET"
}

Glossario

Le definizioni chiave degli elementi nel payload della richiesta sono articolate di seguito:

Parametro Obbligatorio Descrizione Valori consentiti
Nome del Report Sì Nome da assegnare al report corda
Descrizione NO Descrizione del report creato corda
QueryId Sì Report query ID corda
Ora di Inizio Sì Timestamp UTC in corrispondenza del quale inizierà la generazione del report.
Il formato dovrebbe essere: aaaa-MM-ggTHH:mm:ssZ		 corda
Esegui ora NO Questo parametro deve essere utilizzato per creare un report che verrà eseguito una sola volta. StartTime, RecurrenceInterval, e RecurrenceCount vengono ignorati se è impostato su true. Il report viene eseguito immediatamente in modo asincrono vero/falso
QueryStartTime NO Facoltativamente, specifica l'ora di inizio per la query che estrae i dati. Questo parametro è applicabile solo per i report ExecuteNow di esecuzione una tantum impostati su true. L'impostazione di questo parametro sostituisce l'opzione TIMESPAN specificata nella query. Il formato deve essere aa-MM-ggTHH:mm:ssZ Timestamp come stringa
QueryEndTime NO Facoltativamente, specifica l'ora di fine per la query che estrae i dati. Questo parametro è applicabile solo per i report ExecuteNow di esecuzione una tantum impostati su true. L'impostazione di questo parametro sostituisce l'opzione TIMESPAN specificata nella query. Il formato deve essere aa-MM-ggTHH:mm:ssZ Timestamp come stringa
RecurrenceInterval Sì Frequenza in ore in cui deve essere generato il report.
Il valore minimo è 4 e il valore massimo è 2160.		 numero intero
Conteggio ricorrenza NO Numero di report da generare. numero intero
Formato NO Formato di file del file esportato.
Il valore predefinito è CSV.		 "CSV"/"TSV"
CallbackUrl NO URL raggiungibile pubblicamente che può essere configurato facoltativamente come destinazione di richiamata Stringa (URL http)
Metodo Callback NO Il metodo da utilizzare per il callback OTTIENI/PUBBLICA

Risposta di esempio

Il payload della risposta è strutturato come segue:

Codici di risposta: 200, 400, 401, 403, 404, 500

Esempio di payload della risposta:

{
  "value": [
    {
      "reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
      "reportName": "Top10_CustomersReport",
      "description": "Top 10 customers by revenue for last month",
      "queryId": "ec8366a4-d96e-4194-8c37-d5dbc0639033",
      "query": "SELECT CustomerName, Product, BilledRevenueUSD FROM CustomersAndTenants ORDER BY BilledRevenueUSD LIMIT 10 TIMESPAN LAST_MONTH",
      "user": "GAUser@PITEST2.onmicrosoft.com",
      "createdTime": "2021-03-30T13:11:58Z",
      "modifiedTime": null,
      "executeNow": false,
      "startTime": "2021-03-31T18:41:00Z",
      "reportStatus": "Active",
      "recurrenceInterval": 24,
      "recurrenceCount": 100,
      "callbackUrl": "https://<SampleCallbackUrl>",
      "callbackMethod": "GET",
      "format": "csv"
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": "Report created successfully",
  "statusCode": 200,
  "dataRedacted": false
}

Glossario

Le definizioni chiave degli elementi della risposta sono articolate di seguito:

Parametro Descrizione
Id report Identificatore univoco universale (UUID) del report che hai creato.
Nome del Report Nome assegnato al report nel payload della richiesta
Descrizione Descrizione specificata durante la creazione del report
QueryId ID query passato al momento della creazione del report
Quesito Testo della query che verrà eseguita per questo report
Utente ID utente usato per creare il report
CreatedTime Ora UTC in cui è stato creato il report, in questo formato: aaaa-MM-ggTHH:mm:ssZ
Tempo modificato Ora UTC dell'ultima modifica apportata al report in questo formato: aaaa-MM-ggTHH:mm:ssZ
Esegui ora ExecuteNow flag impostato al momento della creazione del report
Ora di Inizio Ora UTC L'esecuzione del report inizierà in questo formato: aaaa-MM-ggTHH:mm:ssZ
Stato del rapporto Stato dell'esecuzione del report. I valori possibili sono Paused, Active, e Inactive
RecurrenceInterval Intervallo di ricorrenza specificato durante la creazione del report
Conteggio ricorrenza Conteggio delle ricorrenze fornito durante la creazione del report.
CallbackUrl URL di callback fornito nella richiesta
Metodo Callback Metodo di callback fornito nella richiesta
Formato Formato dei file di report. I valori possibili sono CSV o TSV.
Conteggio totale Numero di record nella matrice Value
StatusCode Codice risultato
Messaggio I valori possibili sono 200, 400, 401, 403, 500. Messaggio di stato dall'esecuzione dell'API

Ottenere l'API per l'esecuzione dei report

È possibile utilizzare questo metodo per eseguire una query sullo stato dell'esecuzione di un report utilizzando il ReportId ricevuto dall'API Crea report. Il metodo restituisce il collegamento di download del report se il report è pronto per il download. In caso contrario, il metodo restituisce lo stato. È anche possibile usare questa API per ottenere tutte le esecuzioni che si sono verificate per un determinato report.

Importante

Questa API ha parametri di query predefiniti impostati per executionStatus=Completed e getLatestExecution=true. Di conseguenza, la chiamata all'API prima della prima esecuzione corretta del report restituirà 404. Le esecuzioni in sospeso possono essere ottenute impostando executionStatus=Pending.

Sintassi della richiesta

Metodo URI della richiesta
OTTIENI https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}

Header di richiesta

Intestazione TIPO Descrizione
Autorizzazione corda Obbligatorio. Token di accesso Microsoft Entra. Il formato è Bearer <token>.
Tipo di Contenuto corda Application/JSON

Parametro del percorso

Nome del parametro Obbligatorio TIPO Descrizione
ID del rapporto Sì corda Filtrare per ottenere i dettagli di esecuzione solo dei report con il reportId specificato in questo argomento. È possibile specificare più reportId separandoli con un punto e virgola ";"

Query parameter (Parametro di query)

Nome del parametro Obbligatorio TIPO Descrizione
executionId NO corda Filtrare per ottenere i dettagli dei soli report con l'executionId specificato in questo argomento. È possibile specificare più executionId separandoli con un punto e virgola ";".
stato di esecuzione NO Stringa/enum Filtrare per ottenere i dettagli dei soli report con executionStatus specificato in questo argomento.
I valori validi sono: Pending, Running, Paused, e Completed.
Il valore predefinito è Completed.
È possibile specificare più stati separandoli con un punto e virgola ";".
getLatestExecution NO booleano L'API restituirà i dettagli dell'esecuzione più recente. Per impostazione predefinita, questo parametro è impostato su true.
Se si sceglie di passare il valore di questo parametro come false, l'API restituirà le istanze di esecuzione degli ultimi 90 giorni.

Payload della richiesta di esempio

Nessuno

Risposta di esempio

Il payload della risposta è strutturato come segue:

Codici di risposta: 200, 400, 401, 403, 404, 500

Esempio di payload della risposta:

{
  "value": [
    {
      "executionId": "906931dc-4f2f-4195-bbb2-d7295c7550d3",
      "reportId": "d9548477-16d4-492a-bf9c-0cf91a9f69bf",
      "recurrenceInterval": 24,
      "recurrenceCount": 100,
      "callbackUrl": null,
      "callbackMethod": null,
      "format": "csv",
      "executionStatus": "Completed",
      "reportLocation": null,
      "reportAccessSecureLink": "https://<path to report for download>",
      "reportExpiryTime": null,
      "reportGeneratedTime": "2021-03-31T18:41:00Z"
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": null,
  "statusCode": 200,
  "dataRedacted": false
}

Al termine dell'esecuzione del report, viene visualizzato lo stato di esecuzione Completed. È possibile scaricare il report selezionando l'URL in reportAccessSecureLink.

Glossario

Definizioni chiave degli elementi nella risposta.

Parametro Descrizione
ExecutionId Identificatore univoco universale (UUID) dell'istanza di esecuzione
Id report ID del report associato all'istanza di esecuzione
RecurrenceInterval Intervallo di ricorrenza specificato durante la creazione del report
Conteggio ricorrenza Numero di ricorrenze specificato durante la creazione del report
CallbackUrl URL di callback associato all'istanza di esecuzione
Metodo Callback Metodo di callback associato all'istanza di esecuzione
Formato Formato del file generato alla fine dell'esecuzione
Stato di esecuzione Stato dell'istanza di esecuzione del report.
I valori validi sono: Pending, Running, Pausede Completed
ReportAccessSecureLink Collegamento tramite il quale è possibile accedere al report in modo sicuro
RapportoScadenzaTempo Ora UTC oltre la quale il collegamento al report scadrà in questo formato: aaaa-MM-ggTHH:mm:ssZ
Tempo generato da rapporti Ora UTC in cui è stato generato il report in questo formato: aaaa-MM-ggTHH:mm:ssZ
Conteggio totale Numero di set di dati nella matrice Valore
StatusCode Codice risultato
I valori possibili sono 200, 400, 401, 403, 404 e 500
Messaggio Messaggio di stato dall'esecuzione dell'API

Prova le API tramite l'URL dell'API swagger

Contenuti correlati