Paradigma di accesso a livello di codice per il marketplace commerciale

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.

1. L'applicazione client può definire un modello/schema di report personalizzato chiamando l'API di creazione query per il report . In alternativa, è possibile usare un modello di report (QueryId) dall'elenco di query di sistema.
2. In caso di esito positivo, l'API Crea modello di report restituisce l'QueryId.
3. L'applicazione client chiama quindi l'API Crea report usando il 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, la Crea API report restituisce l'ReportID.
5. L'applicazione client riceve una notifica all'URI di callback non appena i dati del report sono pronti per il download.
6. L'applicazione client usa quindi l'API Get Report Executions per eseguire una query sullo stato del report con l'intervallo di Report ID e data.
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

Benché vengano fornite query di sistema che è possibile utilizzare per creare report, potete anche creare le vostre proprie query in base alle esigenze aziendali. Per ulteriori informazioni sulle query personalizzate, vedere specifiche delle query personalizzate.

Creare un'API per le query di 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'API Crea Report direttamente usando i QueryIds 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 SKU a pagamento dal dataset ISVUsage per l'ultimo mese.

Sintassi della richiesta

'intestazione richiesta

parametro Path

Nessuno

parametro di query

Nessuno

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.

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.

API per la creazione di report

Al completamento della creazione di un modello di report personalizzato e con la ricezione del QueryID come parte della risposta alla Creare Query Di Report, questa API può essere utilizzata per programmare 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

l'intestazione richiesta

parametro Path

Nessuno

parametro di query

Nessuno

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.

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.

Ottieni API esecuzioni rapporto

È possibile usare questo metodo per eseguire una query sullo stato di un'esecuzione del report usando il ReportId ricevuto dalla Create Report API. 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.

Sintassi della richiesta

'intestazione richiesta

parametro Path

Nessuno

parametro di query

Payload della richiesta

Nessuno

Risposta di esempio

Il payload della risposta è strutturato come segue:

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

Esempio di contenuto 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 esecuzione Completed. È possibile scaricare il report selezionando l'URL nel reportAccessSecureLink.

Glossario

Definizioni chiave degli elementi nella risposta.

È possibile provare le API tramite l'URL dell'API Swagger .

Contenuto correlato

• Effettuare la prima chiamata API per i report di Marketplace Insights