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.