Condividi tramite


Effettuare la prima chiamata API per accedere ai dati del marketplace commerciale analitica

Per un elenco delle API per l'accesso ai dati analitica del marketplace commerciale, vedere API per l'accesso ai dati analitica del marketplace commerciale. Prima di effettuare la prima chiamata API, assicurarsi di soddisfare i prerequisiti per accedere a livello di codice ai dati del marketplace commerciale analitica.

Generazione di token

Prima di chiamare uno dei metodi, è necessario ottenere un token di accesso a Microsoft Entra. È necessario passare il token di accesso Microsoft Entra all'intestazione Authorization di ogni metodo nell'API. Dopo aver ottenuto un token di accesso, si hanno 60 minuti per usarlo prima della scadenza. Dopo la scadenza del token, è possibile aggiornare il token e continuare a usarlo per altre chiamate all'API.

Avviso

Resource='https://graph.microsoft.com' verrà deprecato dopo il 30 agosto 2024. Pianificare la migrazione a Resource='https://api.partnercenter.microsoft.com' di conseguenza.

Fare riferimento a una richiesta di esempio seguente per la generazione di un token. I tre valori necessari per generare il token sono clientId, clientSecrete tenantId. Il resource parametro deve essere impostato su https://api.partnercenter.microsoft.com.

Esempio di richiesta:

curl --location --request POST 'https://login.microsoftonline.com/{TenantId}/oauth2/token' \
--header 'return-client-request-id: true' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'resource=https://api.partnercenter.microsoft.com' \
--data-urlencode 'client_id={client_id}' \
--data-urlencode 'client_secret={client_secret}' \
--data-urlencode 'grant_type=client_credentials'

Esempio di risposta:

{
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "3599",
    "expires_on": "1612794445",
    "not_before": "1612790545",
    "resource": "https://api.partnercenter.microsoft.com",
    "access_token": {Token}
}

Per altre informazioni su come ottenere un token Microsoft Entra per l'applicazione, vedere Chiamate da servizio a servizio tramite credenziali client (segreto condiviso o certificato).

Chiamata API a livello di codice

Dopo aver ottenuto il token Microsoft Entra come descritto nella sezione precedente, seguire questa procedura per creare il primo report di accesso a livello di codice.

I dati possono essere scaricati dai set di dati seguenti (datasetName):

Nome del report Nome del set di dati nell'API
Ordinamento ISVOrder
Utilizzo ISVUsage
Customer ISVCustomer
Informazioni dettagliate sul Marketplace ISVMarketplaceInsights
Ricavi ISVRevenue
Fidelizzazione ISVOfferRetention
Qualità del servizio ISVQualityOfService
Licenza ISVLicense
Versione dell'immagine della macchina virtuale ISVVMImageVersion

Le sezioni seguenti illustrano esempi di come accedere OrderId a livello di codice dal set di dati ISVOrder.

Passaggio 1: Effettuare una chiamata REST usando l'API Get Datasets

La risposta DELL'API fornisce il nome del set di dati da cui è possibile scaricare il report. Per il set di dati specifico, la risposta api fornisce anche l'elenco di colonne selezionabili che possono essere usate per il modello di report personalizzato.

Esempio di richiesta:

curl 
--location 
--request GET 'https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledDataset ' \ 
--header 'Authorization: Bearer <AzureADToken>'

Esempio di risposta:

{
    "value": [
        {
            "datasetName": "ISVOrder",
            "selectableColumns": [
                "MarketplaceSubscriptionId",
                "MonthStartDate",
                "OfferType",
                "AzureLicenseType",
                "MarketplaceLicenseType",
                "SKU",
                "CustomerCountry",
                "IsPreviewSKU",
                "AssetId",
                "Quantity",
                "CloudInstanceName",
                "IsNewCustomer",
                "OrderStatus",
                "OrderCancelDate",
                "CustomerCompanyName",
                "OrderPurchaseDate",
                "OfferName",
                "IsPrivateOffer",
                "TermStartDate",
                "TermEndDate",
                "PurchaseRecordId",
                "PurchaseRecordLineItemId",
                "BilledRevenue",
                "Currency",
                "HasTrial",
                "IsTrial",
                "TrialEndDate",
                "OrderAction",
                "QuantityChanged",
                "EventTimestamp",
                "CustomerId",
                "BillingAccountId",
                "PlanId",
                "BillingTerm",
                "BillingPlan",
                "ReferenceId",
                "AutoRenew",
                "OrderVersion",
                "ListPriceUSD",
                "DiscountPriceUSD",
                "IsPrivatePlan",
                "OfferId",
                "PrivateOfferId",
                "PrivateOfferName",
                "BillingId",
                "Version",
                "CustomerAdjustmentUSD",
                "MultiParty",
                "PartnerInfo"
            ],
            "availableMetrics": [],
            "availableDateRanges": [
                "LAST_MONTH",
                "LAST_3_MONTHS",
                "LAST_6_MONTHS",
                "LAST_1_YEAR",
                "LIFETIME"
            ],
            "minimumRecurrenceInterval": 1
        },
    ],
    "totalCount": 1,
    "message": "Dataset fetched successfully",
    "statusCode": 200
}

Passaggio 2: Creare la query personalizzata

In questo passaggio si userà l'ID ordine del report Ordini per creare una query personalizzata per il report desiderato. Il valore predefinito timespan se non specificato nella query è di sei mesi.

Esempio di richiesta:

curl 
--location 
--request POST ' https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries' \ 
--header ' Authorization: Bearer <AzureAD_Token>' \ 
--header 'Content-Type: application/json' \ 
--data-raw 
            '{ 
                "Query": "SELECT OrderId from ISVOrder", 
                "Name": "ISVOrderQuery1", 
                "Description": "Get a list of all Order IDs" 
             }'

Esempio di risposta:

{
    "value": [
        {
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "name": "ISVOrderQuery1",
            "description": "Get a list of all Order IDs",
            "query": "SELECT OrderId from ISVOrder",
            "type": "userDefined",
            "user": "142344300",
            "createdTime": "2024-01-06T05:38:34",
            "modifiedTime": null
        }
    ],
    "totalCount": 1,
    "message": "Query created successfully",
    "statusCode": 200
}

Al termine dell'esecuzione della query, viene generato un queryId oggetto che deve essere usato per generare il report.

Passaggio 3: Eseguire l'API di query di test

In questo passaggio si userà l'API di query di test per ottenere le prime 100 righe per la query creata.

Esempio di richiesta:

curl 
--location 
--request GET 'https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledQueries/testQueryResult?exportQuery=SELECT%20OrderId%20from%20ISVOrder' \ 
--header ' Authorization: Bearer <AzureADToken>'

Esempio di risposta:

{
    "value": [
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2ba8"
        },
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bb8"
        },
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bc8"
        },
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bd8"
        },
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2be8"
        },
               .
               .
               .

        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf0"
        },
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf1"
        },
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf2"
        },
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf3"
        },
        {
            "OrderId": "086365c6-9c38-4fba-904a-6228f6cb2bf4"
        }
    ],
    "totalCount": 100,
    "message": null,
    "statusCode": 200
}

Passaggio 4: Creare il report

In questo passaggio si userà l'oggetto generato QueryId in precedenza per creare il report.

Esempio di richiesta:

curl 
--location 
--request POST 'https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport' \ 
--header ' Authorization: Bearer <AzureADToken>' \ 
--header 'Content-Type: application/json' \ 
--data-raw 
                 '{
                   "ReportName": "ISVReport1",
                   "Description": "Report for getting list of Order Ids",
                   "QueryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
                   "StartTime": "2024-01-06T19:00:00Z",
                   "RecurrenceInterval": 48,
                   "RecurrenceCount": 20,
                    "Format": "csv"
                  }'

Esempio di risposta:

{
    "value": [
        {
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "reportName": "ISVReport1",
            "description": "Report for getting list of Order Ids",
            "queryId": "78be43f2-e35f-491a-8cd5-78fe14194f9c",
            "query": "SELECT OrderId from ISVOrder",
            "user": "142344300",
            "createdTime": "2024-01-06T05:46:00Z",
            "modifiedTime": null,
            "startTime": "2024-01-06T19:00:00Z",
            "reportStatus": "Active",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": null,
            "format": "csv"
        }
    ],
    "totalCount": 1,
    "message": "Report created successfully",
    "statusCode": 200
}

Al termine dell'esecuzione, viene generato un reportId oggetto che deve essere usato per pianificare un download del report.

Passaggio 5: Eseguire l'API Esecuzioni di report

Per ottenere la posizione sicura (URL) del report, si eseguirà ora l'API Esecuzioni report.

Esempio di richiesta:

Curl
--location
--request GET 'https://api.partnercenter.microsoft.com/insights/v1.1/cmp/ScheduledReport/execution/72fa95ab-35f5-4d44-a1ee-503abbc88003' \
--header ' Authorization: Bearer <AzureADToken>' \

Esempio di risposta:

{
    "value": [
        {
            "executionId": "1f18b53b-df30-4d98-85ee-e6c7e687aeed",
            "reportId": "72fa95ab-35f5-4d44-a1ee-503abbc88003",
            "recurrenceInterval": 48,
            "recurrenceCount": 20,
            "callbackUrl": null,
            "format": "csv",
            "executionStatus": "Pending",
            "reportAccessSecureLink": null,
            "reportExpiryTime": null,
            "reportGeneratedTime": null
        }
    ],
    "totalCount": 1,
    "message": null,
    "statusCode": 200
}

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