Freigeben über


Erstellen Ihres ersten API-Aufrufs für den Zugriff auf kommerzielle Marketplace-Analysedaten

Eine Liste der APIs für den Zugriff auf kommerzielle Marketplace-Analysedaten finden Sie unter APIs für den Zugriff auf kommerzielle Marketplace-Analysedaten. Bevor Sie Ihren ersten API-Aufruf ausführen, stellen Sie sicher, dass Sie die Voraussetzungen erfüllt haben, um programmgesteuert auf kommerzielle Marketplace-Analysedaten zuzugreifen.

Tokengenerierung

Bevor Sie eine der Methoden aufrufen, müssen Sie zuerst ein Microsoft Entra-Zugriffstoken abrufen. Sie müssen das Microsoft Entra-Zugriffstoken an den Autorisierungsheader jeder Methode in der API übergeben. Nachdem Sie ein Zugriffstoken erhalten haben, haben Sie 60 Minuten Zeit, es zu verwenden, bevor es abläuft. Nach dem Ablauf können Sie das Token aktualisieren und weiterhin in zukünftigen Aufrufen der API verwenden.

Warnung

Resource='https://graph.microsoft.com' wird nach dem 30. August 2024 nicht mehr unterstützt. Planen Sie die Migration zu Resource='https://api.partnercenter.microsoft.com' entsprechend.

Eine Beispielanforderung zum Generieren eines Tokens finden Sie unten. Die zum Generieren des Tokens erforderlichen drei Werte sind clientId, clientSecret und tenantId. Der resource-Parameter sollte auf https://api.partnercenter.microsoft.com festgelegt werden.

Beispiel für eine Anfrage:

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'

Antwort Beispiel:

{
    "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}
}

Weitere Informationen zum Abrufen eines Microsoft Entra-Tokens für Ihre Anwendung finden Sie unter Dienstaufrufe mithilfe von Clientanmeldeinformationen (freigegebener geheimer Schlüssel oder Zertifikat).

Programmgesteuerter API-Aufruf

Nachdem Sie das Microsoft Entra-Token wie im vorherigen Abschnitt beschrieben abgerufen haben, führen Sie die folgenden Schritte aus, um Ihren ersten programmgesteuerten Zugriffsbericht zu erstellen.

Daten können aus den folgenden Datasets (datasetName) heruntergeladen werden:

Berichtsname Datasetname in API
Auftrag ISVOrder
Verbrauch Isvusage
Kreditor ISVCustomer
Marketplace Insights ISVMarketplaceInsights
Umsatzerlös ISVRevenue
Kundenaufbewahrung ISVOfferRetention
Servicequalität ISVQualityOfService
Lizenz ISVLicense
VM-Imageversion ISVVMImageVersion

Die folgenden Abschnitte zeigen Beispiele für den programmgesteuerten Zugriff OrderId über das ISVOrder-Dataset.

Schritt 1: Erstellen eines REST-Aufrufs mithilfe der API zum Abrufen von Datasets

Die API-Antwort enthält den Namen des Datasets, von dem aus Sie den Bericht herunterladen können. Die API-Antwort für das jeweilige Dataset enthält auch die Liste der auswählbaren Spalten, die für Ihre benutzerdefinierte Berichtsvorlage verwendet werden können.

Beispiel für eine Anfrage:

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

Antwort Beispiel:

{
    "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
}

Schritt 2: Erstellen der benutzerdefinierten Abfrage

In diesem Schritt verwenden wir die Auftrags-ID aus dem Bericht „Bestellungen“, um eine benutzerdefinierte Abfrage für den gewünschten Bericht zu erstellen. Wenn der Standardwert für timespan nicht in der Abfrage angegeben ist, beträgt er sechs Monate.

Beispiel für eine Anfrage:

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" 
             }'

Antwort Beispiel:

{
    "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
}

Bei erfolgreicher Ausführung der Abfrage wird eine queryId generiert, die zum Generieren des Berichts verwendet werden muss.

Schritt 3: Ausführen der Testabfrage-API

In diesem Schritt verwenden wir die Testabfrage-API, um die obersten 100 Zeilen für die erstellte Abfrage abzurufen.

Beispiel für eine Anfrage:

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

Antwort Beispiel:

{
    "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
}

Schritt 4: Erstellen des Berichts

In diesem Schritt verwenden wir die zuvor generierte QueryId, um den Bericht zu erstellen.

Beispiel für eine Anfrage:

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"
                  }'

Antwort Beispiel:

{
    "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
}

Bei erfolgreicher Ausführung wird eine reportId generiert, die verwendet werden muss, um einen Download des Berichts zu planen.

Schritt 5: Ausführen der Berichtsausführungs-API

Um den sicheren Speicherort (URL) des Berichts abzurufen, führen wir nun die Berichtsausführungs-API aus.

Beispiel für eine Anfrage:

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

Antwort Beispiel:

{
    "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
}

Sie können die APIs über die Swagger-API-URL testen.