最初の API 呼び出しを行って、コマーシャルマーケットプレース分析データにアクセスする

[アーティクル]
06/14/2024

コマーシャルマーケットプレース分析データにアクセスするための API の一覧については、コマーシャルマーケットプレース分析データにアクセスするための API に関するページを参照してください。最初の API 呼び出しを行う前に、コマーシャルマーケットプレースの分析データにプログラムでアクセスするために前提条件を満たしていることを確認します。

トークンの生成

いずれかのメソッドを呼び出す前に、まず Microsoft Entra アクセストークンを取得する必要があります。 API の各メソッドの Authorization ヘッダーに Microsoft Entra アクセストークンを渡す必要があります。アクセストークンを取得したら、期限が切れる 60 分が経過する前に使用します。トークンの有効期限が切れた後は、トークンを更新してそれ以降の API 呼び出しで引き続き使用できます。

警告

Resource='https://graph.microsoft.com' は、2024 年 8 月 30 日以降に非推奨になります。それに応じて Resource='https://api.partnercenter.microsoft.com' への移行を計画してください。

トークンの生成については、以下の要求のサンプルを参照してください。トークンを生成するために必要な 3 つの値は、clientId、clientSecret、および tenantId です。 resource パラメーターは https://api.partnercenter.microsoft.com に設定する必要があります。

要求の例:

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'

応答の例:

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

アプリケーションの Microsoft Entra トークンを取得する方法の詳細については、「クライアント資格情報 (共有シークレットまたは証明書)を使用したサービス呼び出しへのサービスの提供」を参照してください。

プログラムによる API 呼び出し

前のセクションで説明したように Microsoft Entra トークンを取得したら、次の手順に従って、最初のプログラムによるアクセスレポートを作成します。

データは、次のデータセット (datasetName) からダウンロードできます。

Report Name	API のデータセット名
注文	ISVOrder
使用方法	ISVUsage
顧客	ISVCustomer
Marketplace の分析情報	ISVMarketplaceInsights
Revenue	ISVRevenue
顧客リテンション期間	ISVOfferRetention
サービスの品質	ISVQualityOfService
ライセンス	ISVLicense
VM イメージのバージョン	ISVVMImageVersion

次のセクションでは、ISVOrder データセットから OrderId にプログラムでアクセスする方法の例を示します。

手順 1: データセットの取得 API を使用して REST 呼び出しを行う

この API 応答では、レポートをダウンロードできるデータセット名が提供されます。特定のデータセットについては、この API 応答でカスタムレポートテンプレートに使用できる選択可能な列の一覧も提供されます。

要求の例:

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

応答の例:

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

手順 2: カスタムクエリを作成する

この手順では、注文レポートの注文 ID を使用して、目的のレポートのカスタムクエリを作成します。クエリで指定されていない場合の既定の timespan は、6 か月です。

要求の例:

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

応答の例:

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

クエリが正常に実行されると、レポートを生成するために使用する必要がある queryId が生成されます。

手順 3: テストクエリ API を実行する

この手順では、テストクエリ API を使用して、作成されたクエリの上位 100 行を取得します。

要求の例:

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

応答の例:

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

手順 4: レポートを作成する

この手順では、以前に生成した QueryId を使用してレポートを作成します。

要求の例:

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

応答の例:

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

正常に実行されると、レポートのダウンロードをスケジュールするために使用する必要がある reportId が生成されます。

手順 5: レポート実行 API を実行する

レポートの安全な場所 (URL) を取得するために、レポート実行 API を実行します。

要求の例:

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

応答の例:

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

Swagger API URLを使用して API を試すことができます。

プログラムによるアクセスのパラダイム

次の方法で共有

最初の API 呼び出しを行って、コマーシャルマーケットプレース分析データにアクセスする

トークンの生成

プログラムによる API 呼び出し

手順 1: データセットの取得 API を使用して REST 呼び出しを行う

手順 2: カスタムクエリを作成する

手順 3: テストクエリ API を実行する

手順 4: レポートを作成する

手順 5: レポート実行 API を実行する

フィードバック

その他のリソース

次の方法で共有

最初の API 呼び出しを行って、コマーシャル マーケットプレース分析データにアクセスする

トークンの生成

プログラムによる API 呼び出し

手順 1: データセットの取得 API を使用して REST 呼び出しを行う

手順 2: カスタム クエリを作成する

手順 3: テスト クエリ API を実行する

手順 4: レポートを作成する

手順 5: レポート実行 API を実行する

関連するコンテンツ

フィードバック

その他のリソース

最初の API 呼び出しを行って、コマーシャルマーケットプレース分析データにアクセスする

手順 2: カスタムクエリを作成する

手順 3: テストクエリ API を実行する