Compartilhar via

Faça sua primeira chamada à API para acessar dados de análise de insights de parceiros

Para obter uma lista das APIs para acesso a dados de análise de insights de parceiros, consulte APIs para acesso a dados de análise de insights de parceiros. Antes de fazer sua primeira chamada à API, verifique se você cumpre os pré-requisitos para acessar programaticamente dados de análise de insights de parceiros.

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. Após o token expirar, você pode atualizá-lo e continuar usando-o em mais chamadas à API.

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 de recurso 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' \
--header 'Cookie: fpc=Ar2GMei7JwdKg4Y4onHrMpvxqd4FAQAAAEhU_tcOAAAA; stsservicecookie=estsfd; x-ms-gateway-slice=estsfd' \
--data-urlencode 'resource= https://api.partnercenter.microsoft.com' \
--data-urlencode 'client_id= ' \
--data-urlencode 'client_secret= ' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'scope=openid' \
--data-urlencode 'username= ' \
--data-urlencode 'password= '

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 Acessar dados de análise usando os serviços da Store.

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):

  • CustomersAndTenants
  • SeatsSubscriptionsAndRevenue
  • AzureUsage
  • MSLearn
  • OfficeUsage
  • Perfil
  • TrainingCompletions
  • DynamicsUsage
  • CompetencySummaryHistory
  • PowerBIUsage
  • EMSUsage
  • CompetencyPeformanceRequirement
  • ResellerPerformance
  • CLASAgreementRenewalsPropensity
  • CLASAzurePropensity
  • CLASD365Propensity
  • CLASM365Propensity
  • TeamsUsage3PApps
  • TeamsUsageWorkload
  • TeamsUsageMeetingsAndCalls

A seção a seguir mostra exemplos de como acessar SubscriptionId programaticamente do conjunto de dados DynamicsUsage.

Etapa 1: fazer uma chamada REST usando a API de obtenção de conjuntos de dados

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. Você também pode consultar as Definições de Dados para obter os nomes das colunas.

Exemplo de solicitação

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

Exemplo de resposta

{
  "value": [
    {
      "datasetName": "DynamicsUsage",
      "selectableColumns": [
        "PGAMpnId",
        "SubscriptionId",
        "SubscriptionStartDate",
        "SubscriptionEndDate",
        "SubscriptionStatus",
        "Month",
        "RevSumDivisionName",
        "RevSumCategoryName",
        "SKU",
        "SKUId",
        "FreeVsPaidSKU",
        "SalesModel",
        "DetailedSalesModel",
        "CustomerName",
        "CustomerTenantId",
        "CustomerTpid",
        "CustomerSegment",
        "CustomerMarket",
        "MPNId",
        "PartnerName",
        "PartnerLocation",
        "PartnerAttachType",
        "AvailableSeats",
        "AssignedSeats",
        "ActiveSeats",
        "DeploymentOpportunity",
        "ActiveUsagePercent"
      ],
      "availableMetrics": [
        "SubscriptionCount",
        "TotalAssignedSeats",
        "TotalSoldSeats",
        "TotalActiveSeats",
        "TotalRevenueAndACR",
        "CustomerCount",
        "CustomerTenantCount"
      ],
      "availableDateRanges": [
        "LAST_MONTH",
        "LAST_3_MONTHS",
        "LAST_6_MONTHS",
        "LAST_1_YEAR",
        "LIFETIME"
      ],
      "minimumRecurrenceInterval": 24
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": "Dataset fetched successfully",
  "statusCode": 200,
  "dataRedacted": false
}

Etapa 2: criar uma consulta personalizada

Nesta etapa, usaremos SubscriptionId do conjunto de dados DynamicsUsage para criar uma consulta personalizada para o relatório que desejamos. O período padrão, se não for especificado na consulta, é de seis meses.

Exemplo de solicitação

curl
--location
--request POST 'https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledQueries' \
--header ' Authorization: Bearer <AADToken>' \
--header 'Content-Type: application/json' \
--data-raw
{
  "Name": "SubscriptionId Dynamics ",
  "Description": "List of Subscription Id from DynamicsUsage",
  "Query": "SELECT SubscriptionId from DynamicsUsage "
            }"

Exemplo de resposta

{
  "value": [
    {
      "queryId": "7d19305c-56db-4edc-b776-428340e3a9c8",
      "name": "SubscriptionId Dynamics",
      "description": "List of Subscription Id from DynamicsUsage",
      "query": "SELECT SubscriptionId from DynamicsUsage",
      "type": "userDefined",
      "user": "GAUser@PITEST2.onmicrosoft.com",
      "createdTime": "2021-03-31T07:28:37Z"
    }
 ],
  "nextLink": null,
  "totalCount": 1,
  "message": "Query created successfully",
  "statusCode": 200,
  "dataRedacted": false
}

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/mpn/ScheduledQueries/testQueryResult?queryId=7d19305c-56db-4edc-b776-428340e3a9c8' \
--header ' Authorization: Bearer <AADToken>'

Exemplo de resposta

{
  "value": [
    {
      "SubscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
    },
    {
      "SubscriptionId": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f"
    },
    {
      "SubscriptionId": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a"
    },
    {
      "SubscriptionId": "dddd3d3d-ee4e-ff5f-aa6a-bbbbbb7b7b7b"
    },
    {
      "SubscriptionId": "eeee4efe-ff5f-aa6a-bb7b-cccccc8c8c8c"
    },
    .
    .
    .
    {
      "SubscriptionId": "ffff5f5f-aa6a-bb7b-cc8c-dddddd9d9d9d"
    },
    {
      "SubscriptionId": "aaaa6a6a-bb7b-cc8c-dd9d-eeeeee0e0e0e"
    },
    {
      "SubscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e"
    },
    {
      "SubscriptionId": "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f"
    },
    {
      "SubscriptionId": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a"
    }
  ],
  "nextLink": null,
  "totalCount": 100,
  "message": null,
  "statusCode": 200,
  "dataRedacted": false
}

Etapa 4: criar o relatório

Nesta etapa, usaremos a QueryId gerada anteriormente para criar o relatório.

Exemplo de solicitação

curl
--location
--request POST 'https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport'\
--header ' Authorization: Bearer <AADToken>' \
--header 'Content-Type: application/json' \
--data-raw
'{
  "ReportName": "DynamicsUsage Subscription ID Report",
  "Description": "Report for getting list of Subscription Id for Dynamics Usage",
  "QueryId": "7d19305c-56db-4edc-b776-428340e3a9c8",
  "StartTime": "2021-04-01T18:41:00Z",
  "ExecuteNow": false,
  "QueryStartTime": "2021-03-31T18:41:00Z",
  "QueryEndTime": "2021-06-30T18:41:00Z",
  "RecurrenceInterval": 48,
  "RecurrenceCount": 20,
  "Format": "csv",
  "CallbackUrl": "https://<SampleCallbackUrl>",
  "CallbackMethod": "GET"
}'

Exemplo de resposta

{
  "value": [
    {
      "reportId": "cdc61cfe-d028-4333-a215-a1df51ccbfd4",
      "reportName": "DynamicsUsage Subscription ID Report",
      "description": "Report for getting list of Subscription Id for Dynamics Usage",
      "queryId": "7d19305c-56db-4edc-b776-428340e3a9c8",
      "query": "SELECT SubscriptionId from DynamicsUsage",
      "user": "GAUser@PITEST2.onmicrosoft.com",
      "createdTime": "2021-03-31T08:15:15Z",
      "modifiedTime": null,
      "executeNow": false,
      "startTime": "2021-04-01T18:41:00Z",
      "reportStatus": "Active",
      "recurrenceInterval": 48,
      "recurrenceCount": 20,
      "callbackUrl": "https://<SampleCallbackUrl>",
      "CallbackMethod": "GET",
      "format": "csv"
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": "Report created successfully",
  "statusCode": 200,
  "dataRedacted": false
}

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

Nesta etapa, usaremos a API de Execuções de Relatório para obter a URL (localização segura) do relatório.

Exemplo de solicitação

Curl
--location
--request GET 'https://api.partnercenter.microsoft.com/insights/v1/mpn/ScheduledReport/execution/ cdc61cfe-d028-4333-a215-a1df51ccbfd4?getLatestExecution=true'\
--header ' Authorization: Bearer <AADToken>' \

Exemplo de resposta

{
  "value": [
    {
      "executionId": "315eb63e-e2b2-41a2-ad8e-790b040fdce3",
      "reportId": "cdc61cfe-d028-4333-a215-a1df51ccbfd4",
      "recurrenceInterval": 48,
      "recurrenceCount": 20,
      "callbackUrl": null,
      "CallbackMethod": null,
      "format": "csv",
      "executionStatus": "Pending",
      "reportLocation": null,
      "reportAccessSecureLink": null,
      "reportExpiryTime": null,
      "reportGeneratedTime": null
    }
  ],
  "nextLink": null,
  "totalCount": 1,
  "message": null,
  "statusCode": 200,
  "dataRedacted": false
}

Experimente as APIs por meio do URL da API do swagger.