Paradigma di accesso a livello di codice per il marketplace commerciale

Articolo
01/24/2024

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.

Figura 1: Flusso generale del modello di chiamata API

Questo elenco fornisce altri dettagli sulla figura 1.

L'applicazione client può definire lo schema/modello di report personalizzato chiamando l'API Crea query report. In alternativa, è possibile usare un modello di report (QueryId) dall'elenco di query di sistema.
In caso di esito positivo, l'API Crea modello di report restituisce .QueryId
L'applicazione client chiama quindi l'API Crea report usando insieme alla QueryID data di inizio del report, all'intervallo di ripetizione, alla ricorrenza e a un URI di callback facoltativo.
In caso di esito positivo, l'API Crea report restituisce .ReportID
L'applicazione client riceve una notifica all'URI di callback non appena i dati del report sono pronti per il download.
L'applicazione client usa quindi l'API Get Report Executions per eseguire una query sullo stato del report con l'intervallo Report ID di date e .
In caso di esito positivo, viene restituito il collegamento di download del report e l'applicazione può avviare il download dei dati.

Specifica del linguaggio di query del report

Anche se vengono fornite query di sistema che è possibile usare per creare report, è anche possibile creare query personalizzate in base alle esigenze aziendali. Per altre informazioni sulle query personalizzate, vedere Specifica di query personalizzata.

Creare un'API di query del report

Questa API consente di creare query personalizzate che definiscono il set di dati da cui devono essere esportate colonne e 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 l'APICrea report direttamente usando i valori QueryId delle query di sistema fornite.

Nell'esempio seguente viene illustrato come creare una query personalizzata per ottenere l'utilizzo normalizzato e gli addebiti finanziari stimati per GLI SKU A PAGAMENTO dal set di dati ISVUsage per l'ultimo mese.

Sintassi della richiesta

metodo	URI della richiesta
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries`

Intestazione della richiesta

Intestazione	Type	Descrizione
Autorizzazione	stringa	Obbligatorio. Token di accesso Microsoft Entra. Il formato è `Bearer <token>`.
Content-Type	`string`	`application/JSON`

Parametro Path

None

Parametro di query

None

Esempio di payload della richiesta

{
    "Name": "ISVUsageQuery",
    "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
    "Query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH"
}

Glossario

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

Parametro	Richiesto	Descrizione	Valori consentiti
`Name`	Sì	Nome descrittivo della query	string
`Description`	No	Descrizione della query creata	string
`Query`	Sì	Stringa di query basata sulle esigenze aziendali	string

Nota

Per esempi di query personalizzate, vedere 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": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": " ISVUsageQuery",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "query": " SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34Z"
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

Glossario

Questa tabella fornisce le definizioni chiave degli elementi nella risposta.

Parametro	Descrizione
`QueryId`	Identificatore univoco universale (UUID) della query creata
`Name`	Nome specificato nel payload della richiesta durante la creazione della query
`Description`	Descrizione fornita nel payload della richiesta durante la creazione di query
`Query`	Query report personalizzata fornita nel payload della richiesta durante la creazione di query
`Type`	Impostare su `userDefined` per le query create manualmente
`User`	ID utente usato per creare la query
`CreatedTime`	Ora UTC in cui è stata creata la query. Formato: aaaa-MM-ggTHH:mm:ssZ
`TotalCount`	Numero di record nella matrice Value
`StatusCode`	Codice risultato I valori possibili sono 200, 400, 401, 403, 500
`message`	Messaggio di stato dall'esecuzione dell'API

Creare un'API report

Durante la creazione di un modello di report personalizzato e la QueryID ricezione di come parte della risposta crea query di report, 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.

Sintassi della richiesta

metodo	URI della richiesta
POST	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport`

Intestazione della richiesta

Intestazione	Type	Descrizione
Autorizzazione	stringa	Obbligatorio. Token di accesso Microsoft Entra. Il formato è `Bearer <token>`.
Tipo di contenuto	string	`application/JSON`

Parametro Path

None

Parametro di query

None

Esempio di payload della richiesta

{
  "ReportName": "ISVUsageReport",
  "Description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
  "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c ",
  "StartTime": "2021-01-06T19:00:00Z ",
  "executeNow": false,
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>"
  "callbackMethod": "GET",
}

Glossario

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

Parametro	Richiesto	Descrizione	Valori consentiti
`ReportName`	Sì	Nome descrittivo assegnato al report	Stringa
`Description`	No	Descrizione del report creato	Stringa
`QueryId`	Sì	ID query che deve essere usato per la generazione di report	Stringa
`StartTime`	Sì	Timestamp UTC in corrispondenza del quale inizierà la generazione del report. Il formato deve essere aa-MM-ggTHH:mm:ssZ	Stringa
`ExecuteNow`	No	Questo parametro deve essere usato per creare un report eseguito una sola volta. `StartTimeRecurrenceCount`, `RecurrenceInterval`, e `EndTime` vengono ignorati se è impostato su`true`	Boolean
`QueryStartTime`	No	Facoltativamente, specifica l'ora di inizio per la query che estrae i dati. Questo parametro è applicabile solo per un report `ExecuteNow` di esecuzione una volta impostato su `true`. 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 un report `ExecuteNow` di esecuzione una volta impostato su `true`. 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 è 1 e il valore massimo è 17520	Integer
`RecurrenceCount`	Sì	Numero di report da generare. Il limite dipende dall'intervallo ricorrenza	Integer
`Format`	No	Formato di file del file esportato. Il formato predefinito è CSV	CSV/TSV
`CallbackUrl`	No	URL accessibile pubblicamente che può essere configurato facoltativamente come destinazione di callback	Stringa
`CallbackMethod`	No	Metodo Get/Post che può essere configurato con l'URL di callback	GET/POST
`EndTime`	Sì	Timestamp UTC in corrispondenza del quale terminerà la generazione del report. Il formato deve essere aa-MM-ggTHH:mm:ssZ	String

Nota

Durante la creazione del report, EndTime o combinazione di RecurrenceInterval e RecurrenceCount è obbligatorio.

Risposta di esempio

Il payload della risposta è strutturato come segue:

Codice risposta: 200, 400, 401, 403, 404, 500

Payload della risposta:

{
  "Value": [
    {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVUsageReport",
            "description": "Normalized Usage and Estimated Financial Charges for PAID SKUs",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT UsageDate, NormalizedUsage, EstimatedExtendedChargePC FROM ISVUsage WHERE SKUBillingType = 'Paid' ORDER BY UsageDate DESC TIMESPAN LAST_MONTH",
            "user": "142344300",
            "createdTime": "2024-01-06T05:46:00Z",
            "modifiedTime": null,
            "startTime": "2024-01-06T19:00:00Z",
            "reportStatus": "Active",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": "https://<SampleCallbackUrl>",
            "callbackMethod": "GET",
            "format": "csv"
    }
  ],
  "TotalCount": 1,
  "Message": "Report created successfully",
  "StatusCode": 200
}

Glossario

Questa tabella fornisce le definizioni chiave degli elementi nella risposta.

Parametro	Descrizione
`ReportId`	Identificatore univoco universale (UUID) del report creato
`ReportName`	Nome specificato nel payload della richiesta durante la creazione del report
`Description`	Descrizione fornita nel payload della richiesta durante la creazione del report
`QueryId`	ID query fornito nel payload della richiesta durante la creazione del report
`Query`	Testo della query che verrà eseguito per questo report
`User`	ID utente usato per creare il report
`CreatedTime`	Ora UTC in cui è stato creato il report in questo formato: aa-MM-ggTHH:mm:ssZ
`ModifiedTime`	Ora UTC dell'ultima modifica apportata al report in questo formato: aaaa-MM-ggTHH:mm:ssZ
`ExecuteNow`	Parametro ExecuteNow fornito nel payload della richiesta durante la creazione del report
`queryStartTime`	Ora di inizio della query specificata nel payload della richiesta durante la creazione del report. Questo è applicabile solo se `ExecuteNow` è impostato su "True"
`queryEndTime`	Ora di fine della query specificata nel payload della richiesta durante la creazione del report. Questo è applicabile solo se `ExecuteNow` è impostato su "True"
`StartTime`	Ora di inizio specificata nel payload della richiesta durante la creazione del report
`ReportStatus`	Stato dell'esecuzione del report. I valori possibili sono Paused, Active e Inactive.
`RecurrenceInterval`	Intervallo di ricorrenza specificato nel payload della richiesta durante la creazione del report
`RecurrenceCount`	Numero di ricorrenze rimanenti per il report
`CallbackUrl`	URL di callback fornito nel payload della richiesta durante la creazione del report
`CallbackMethod`	Metodo di callback fornito nel payload della richiesta durante la creazione del report
`Format`	Formato dei file di report forniti nel payload della richiesta durante la creazione del report
`EndTime`	Ora di fine specificata nel payload della richiesta durante la creazione del report. Questo è applicabile solo se `ExecuteNow` è impostato su "True"
`TotalRecurrenceCount`	`RecurrenceCount` specificato nel payload della richiesta durante la creazione del report
`nextExecutionStartTime`	Timestamp UTC all'avvio dell'esecuzione successiva del report
`TotalCount`	Numero di record nella matrice Value
`StatusCode`	Codice risultato. I valori possibili sono 200, 400, 401, 403, 500
`message`	Messaggio di stato dall'esecuzione dell'API

Get report executions API

È possibile usare questo metodo per eseguire una query sullo stato di un'esecuzione di un report usando l'oggetto 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
Recupero	`https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/{reportId}?executionId={executionId}&executionStatus={executionStatus}&getLatestExecution={getLatestExecution}`

Intestazione della richiesta

Intestazione	Type	Descrizione
Autorizzazione	stringa	Obbligatorio. Token di accesso Microsoft Entra. Il formato è `Bearer <token>`.
Tipo di contenuto	string	`application/json`

Parametro Path

None

Parametro di query

Nome parametro	Richiesto	Type	Descrizione
`reportId`	Sì	string	Filtro per ottenere i dettagli di esecuzione solo dei report con `reportId` specificati in questo argomento.
`executionId`	No	string	Filtro per ottenere i dettagli solo dei report con `executionId` specificati in questo argomento. È possibile specificare più `executionIds` valori separandoli con un punto e virgola ";".
`executionStatus`	No	stringa/enumerazione	Filtro per ottenere i dettagli solo dei report con `executionStatus` specificati in questo argomento. I valori validi sono: `Pending`, `Running`, `Paused`e `Completed` Il valore predefinito è `Completed`.
`getLatestExecution`	No	boolean	L'API restituirà i dettagli dell'esecuzione del report più recente. Per impostazione predefinita, il 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

None

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": "a0bd78ad-1a05-40fa-8847-8968b718d00f",
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "recurrenceInterval": 4,
            "recurrenceCount": 10,
            "callbackUrl": null,
            "format": "csv",
            "executionStatus": "Completed",
            "reportAccessSecureLink": "https://<path to report for download>",
            "reportExpiryTime": null,
            "reportGeneratedTime": "2021-01-13T14:40:46Z"
        }
    ],
    "totalCount": 1,
    "message": null,
    "statusCode": 200
}

Al termine dell'esecuzione del report, viene visualizzato lo stato di Completed esecuzione. È 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
`ReportId`	ID report associato all'istanza di esecuzione
`RecurrenceInterval`	Intervallo di ricorrenza specificato durante la creazione del report
`RecurrenceCount`	Numero di ricorrenze specificato durante la creazione del report
`CallbackUrl`	URL di callback associato all'istanza di esecuzione
`CallbackMethod`	Metodo di callback fornito nel payload della richiesta durante la creazione del report
`Format`	Formato del file generato alla fine dell'esecuzione
`ExecutionStatus`	Stato dell'istanza di esecuzione del report. I valori validi sono: `Pending`, `Running`, `Paused`e `Completed`
`ReportLocation`	Percorso in cui viene scaricato il report.
`ReportAccessSecureLink`	Collegamento tramite il quale è possibile accedere al report in modo sicuro
`ReportExpiryTime`	Ora UTC dopo la quale il collegamento al report scadrà in questo formato: aaaa-MM-ggTHH:mm:ssZ
`ReportGeneratedTime`	Ora UTC in cui è stato generato il report in questo formato: aaaa-MM-ggTHH:mm:ssZ
`EndTime`	Ora di fine specificata nel payload della richiesta durante la creazione del report. Questo è applicabile solo se `ExecuteNow` è impostato su "True"
`TotalRecurrenceCount`	`RecurrenceCount` specificato nel payload della richiesta durante la creazione del report
`nextExecutionStartTime`	Timestamp UTC all'avvio dell'esecuzione successiva del report
`TotalCount`	Numero di set di dati nella matrice Valore
`StatusCode`	Codice risultato I valori possibili sono 200, 400, 401, 403, 404 e 500
`message`	Messaggio di stato dall'esecuzione dell'API

Passaggi successivi

È possibile provare le API tramite l'URL dell'API Swagger
Effettuare la prima chiamata API per i report di Marketplace Insights

Share via

Paradigma di accesso a livello di codice per il marketplace commerciale

Specifica del linguaggio di query del report

Creare un'API di query del report

Creare un'API report

Get report executions API

Passaggi successivi

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive