Partilhar via

Faça sua primeira chamada de API para acessar dados de análise do mercado comercial

  • Artigo

Para obter uma lista das APIs para acessar dados de análise do mercado comercial, consulte APIs para acessar dados de análise do mercado comercial. Antes de fazer sua primeira chamada de API, verifique se você atendeu aos pré-requisitos para acessar programaticamente os dados de análise do mercado 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. Depois de obter um token de acesso, você tem 60 minutos para usá-lo antes que ele expire. Depois que o token expirar, você poderá atualizá-lo e continuar a usá-lo para outras chamadas para a API.

Aviso

Resource='https://graph.microsoft.com' será preterido 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, clientSecrete tenantId. O resource parâmetro 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 Serviço para chamadas de serviço usando credenciais de cliente (segredo compartilhado ou certificado).

Chamada de API programática

Depois de obter o Microsoft Entra Token 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
Ordenar ISVOrder
Utilização ISVUsage
Cliente ISVCustomer
Informações 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 de onde 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 seu 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, usaremos o ID do pedido do Relatório de pedidos para criar uma consulta personalizada para o relatório desejado. O padrão timespan , se não especificado na consulta, é de 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, é gerado um queryId que precisa ser usado para gerar o relatório.

Etapa 3: Executar a API de consulta de teste

Nesta etapa, usaremos a API de consulta de teste para obter as 100 principais 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, usaremos o gerado QueryId 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, é gerado um reportId que precisa ser usado para agendar um download do relatório.

Etapa 5: Executar a 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
}

Você pode experimentar as APIs por meio da URL da API do Swagger.

Conteúdos relacionados