Bagikan melalui

Lakukan panggilan API pertama Anda untuk mengakses data analitik marketplace komersial

  • Artikel

Untuk daftar API untuk mengakses data analitik marketplace komersial, lihat API untuk mengakses data analitik marketplace komersial. Sebelum melakukan panggilan API pertama, pastikan Anda memenuhi prasyarat untuk mengakses data analitik marketplace komersial secara terprogram.

Pembuatan token

Sebelum memanggil salah satu metode, Anda harus terlebih dahulu mendapatkan token akses Microsoft Entra. Anda perlu meneruskan token akses Microsoft Entra ke header Otorisasi dari setiap metode di API. Setelah mendapatkan token akses, Anda memiliki waktu 60 menit untuk menggunakannya sebelum kedaluwarsa. Setelah token kedaluwarsa, Anda dapat memperbarui token dan terus menggunakannya untuk panggilan lebih lanjut ke API.

Peringatan

Resource='https://graph.microsoft.com' tidak akan digunakan lagi setelah 30 Agustus 2024. Silakan rencanakan migrasi ke Resource='https://api.partnercenter.microsoft.com' dengan sesuai.

Lihat contoh permintaan di bawah ini untuk menghasilkan token. Tiga nilai yang diperlukan untuk menghasilkan token adalah clientId, clientSecret, dan tenantId. Parameter resource harus diatur ke https://api.partnercenter.microsoft.com.

contoh permintaan :

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'

Contoh respons:

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

Untuk informasi selengkapnya tentang cara mendapatkan token Microsoft Entra untuk aplikasi Anda, lihat Layanan ke panggilan layanan menggunakan kredensial klien (rahasia bersama atau sertifikat).

Panggilan API terprogram

Setelah Anda mendapatkan Microsoft Entra Token seperti yang dijelaskan di bagian sebelumnya, ikuti langkah-langkah ini untuk membuat laporan akses terprogram pertama Anda.

Data dapat diunduh dari himpunan data berikut (datasetName):

Nama Laporan Nama Himpunan Data dalam API
Pesanan ISVOrder
Penggunaan Penggunaan ISV
Pelanggan Pelanggan ISV
Wawasan Marketplace ISVMarketplaceInsights
Pendapatan ISVRevenue
Retensi Pelanggan ISVOfferRetention
Kualitas Layanan ISVQualityOfService
Lisensi Lisensi ISV
Versi Citra VM ISVVMImageVersion

Bagian berikut menunjukkan contoh cara mengakses OrderId secara terprogram dari himpunan data ISVOrder.

Langkah 1: Lakukan panggilan REST menggunakan Get Datasets API

Respons API menyediakan nama himpunan data tempat Anda dapat mengunduh laporan. Untuk himpunan data tertentu, respons API juga menyediakan daftar kolom yang dapat dipilih yang dapat digunakan untuk templat laporan kustom Anda.

contoh permintaan :

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

Contoh respons:

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

Langkah 2: Membuat kueri kustom

Dalam langkah ini, kita akan menggunakan ID Pesanan dari Laporan Pesanan untuk membuat kueri kustom untuk laporan yang kita inginkan. timespan sebagai default jika tidak ditentukan dalam kueri adalah enam bulan.

contoh permintaan :

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

Contoh respons:

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

Ketika kueri berhasil dieksekusi, queryId dihasilkan dan perlu digunakan untuk menghasilkan laporan.

Langkah 3: Jalankan API kueri pengujian

Dalam langkah ini, kita akan menggunakan API kueri pengujian untuk mendapatkan 100 baris teratas untuk kueri yang dibuat.

contoh permintaan:

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

Contoh respons:

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

Langkah 4: Buat laporan

Dalam langkah ini, kita akan menggunakan QueryId yang dibuat sebelumnya untuk membuat laporan.

contoh permintaan :

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

Contoh respons:

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

Pada eksekusi yang berhasil, reportId dihasilkan yang perlu digunakan untuk menjadwalkan unduhan laporan.

Langkah 5: Jalankan API Eksekusi Laporan

Untuk mendapatkan lokasi aman (URL) laporan, kita sekarang akan menjalankan API Eksekusi Laporan.

contoh permintaan :

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

Contoh respons:

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

Anda dapat mencoba API melalui URL API Swagger.

Konten terkait

  • paradigma akses terprogram