Compartilhar via

Fazer sua primeira chamada à API para acessar dados de análise do Marketplace comercial

  • Artigo

Para obter uma lista das APIs para acessar dados de análise do marketplace comercial, consulte APIs para acessar dados de análise do marketplace comercial. Antes de fazer sua primeira chamada à API, verifique se você atendeu aos pré-requisitos para acessar programaticamente os dados de análise do marketplace comercial.

Geração de tokens

Antes de chamar qualquer um dos métodos, você deve primeiro obter um token de acesso do Microsoft Entra. Você precisa passar o token de acesso do Microsoft Entra para o cabeçalho Authorization de cada método na API. Após obter um token de acesso, você tem 60 minutos para usá-lo antes que ele expire. Depois que o token expirar, atualize o token para que você possa continuar a usá-lo em mais chamadas à API.

Aviso

Resource='https://graph.microsoft.com' será descontinuado após 30 de agosto de 2024. Planeje a migração para Resource='https://api.partnercenter.microsoft.com' de acordo.

Consulte uma solicitação de exemplo abaixo para gerar um token. Os três valores necessários para gerar o token são clientId, clientSecret e tenantId. O parâmetro resource deve ser definido como https://api.partnercenter.microsoft.com.

Exemplo de solicitação:

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'

Exemplo de resposta:

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

Para obter mais informações sobre como obter um token do Microsoft Entra para seu aplicativo, consulte Chamadas de serviço a serviço usando credenciais de cliente (segredo compartilhado ou certificado).

Chamada à API programática

Depois de obter o Token do Microsoft Entra, conforme descrito na seção anterior, siga estas etapas para criar seu primeiro relatório de acesso programático.

Os dados podem ser baixados dos seguintes conjuntos de dados (DataSetName):

Nome do Relatório Nome do conjunto de dados na API
Pedido ISVOrder
Uso ISVUsage
Customer ISVCustomer
Insights do Marketplace ISVMarketplaceInsights
Receita ISVRevenue
Retenção de clientes ISVOfferRetention
Qualidade de Serviço ISVQualityOfService
Licença ISVLicense
Versão da imagem da VM ISVVMImageVersion

As seções a seguir mostram exemplos de como acessar OrderId programaticamente a partir do conjunto de dados ISVOrder.

Etapa 1: fazer uma chamada REST usando a API Get Datasets

A resposta da API fornece o nome do conjunto de dados do qual você pode baixar o relatório. Para o conjunto de dados específico, a resposta da API também fornece a lista de colunas selecionáveis que podem ser usadas para o modelo de relatório personalizado.

Exemplo de solicitação:

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

Exemplo de resposta:

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

Etapa 2: criar a consulta personalizada

Nesta etapa, vamos usar a ID do Pedido do Relatório de Pedidos para criar uma consulta personalizada para o relatório que desejamos. O padrão timespan, se não especificado na consulta, é seis meses.

Exemplo de solicitação:

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

Exemplo de resposta:

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

Na execução bem-sucedida da consulta, um queryId é gerado que precisa ser usado para gerar o relatório.

Etapa 3: executar a API de consulta de teste

Nesta etapa, vamos usar a API de consulta de teste para obter as 100 primeiras linhas para a consulta que foi criada.

Exemplo de solicitação:

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

Exemplo de resposta:

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

Etapa 4: criar o relatório

Nesta etapa, vamos usar o QueryId gerado anteriormente para criar o relatório.

Exemplo de solicitação:

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

Exemplo de resposta:

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

Na execução bem-sucedida, um reportId é gerado um que precisa ser usado para agendar um download do relatório.

Etapa 5: executar API de Execuções de Relatório

Para obter o local seguro (URL) do relatório, agora executaremos a API de Execuções de Relatório.

Exemplo de solicitação:

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

Exemplo de resposta:

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

É possível experimentar as APIs por meio da URL da API do Swagger.

Conteúdo relacionado