次の方法で共有


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

コマーシャル マーケットプレース分析データにアクセスするための 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 つの値は、clientIdclientSecret、および 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 を試すことができます。