Compartilhar via

Especificação de consulta personalizada para marketplace comercial

  • Artigo

Os parceiros podem usar essa especificação de consulta para formular facilmente consultas personalizadas para extrair dados de tabelas de análise. As consultas podem ser usadas para selecionar apenas as colunas e métricas desejadas que corresponderem a um determinado critério. No centro da especificação da linguagem está a definição de conjuntos de dados na qual uma consulta personalizada pode ser escrita.

Conjunto de dados

Da mesma forma que algumas consultas são executados em um banco de dados que tem tabelas e colunas, uma consulta personalizada funciona em conjuntos de dados que têm colunas e métricas. A lista completa de conjuntos de dados disponíveis para formular uma consulta pode ser encontrada usando a API de conjuntos de dados.

Aqui está um exemplo de um conjunto de dados mostrado como um JSON.

{
            "datasetName": "ISVUsage",
            "selectableColumns": [
                "MarketplaceSubscriptionId",
                "MonthStartDate",
                "OfferType",
                "AzureLicenseType",
                "MarketplaceLicenseType",
                "SKU",
                "CustomerCountry",
                "IsPreviewSKU",
                "SKUBillingType",
                "VMSize",
                "CloudInstanceName",
                "OfferName",
                "IsPrivateOffer",
                "DeploymentMethod",
                "CustomerName",
                "CustomerCompanyName",
                "UsageDate",
                "IsNewCustomer",
                "CoreSize",
                "TrialEndDate",
                "CustomerCurrencyCC",
                "PriceCC",
                "PayoutCurrencyPC",
                "EstimatedPricePC",
                "UsageReference",
                "UsageUnit",
                "CustomerId",
                "BillingAccountId",
                "MeterDimension",
                "MeterId",
                "PartnerCenterDetectedAnomaly",
                "PublisherMarkedAnomaly",
                "NewReportedUsage",
                "ActionTakenAt",
                "ActionTakenBy",
                "PlanId",
                "ReferenceId",
                "ListPriceUSD",
                "DiscountedPriceUSD",
                "IsPrivatePlan",
                "OfferId",
                "PrivateOfferId",
                "PrivateOfferName",
                "BillingId",
                "PlanType",
                "CustomerAccess",
                "PublisherAccess",
                "CustomerAdjustmentUSD",
                "MultiParty",
                "PartnerInfo",
                "SalesNotes",
                "IsCustomMeter",
                "AssetId",
                "IsMultisolution",
                "VMSubscription"
            ],
            "availableMetrics": [
                "NormalizedUsage",
                "MeteredUsage",
                "RawUsage",
                "EstimatedExtendedChargeCC",
                "EstimatedExtendedChargePC",
                "EstimatedFinancialImpactUSD"
            ],
            "availableDateRanges": [
                "LAST_MONTH",
                "LAST_3_MONTHS",
                "LAST_6_MONTHS",
                "LAST_1_YEAR",
                "LAST_3_YEARS"
            ],
            "minimumRecurrenceInterval": 1
        }

Partes de um conjunto de dados

  • Um nome de conjuntos de dados é como um nome de tabela de banco de dados. Por exemplo, ISVUsage. Um conjuntos de dados tem uma lista de colunas que podem ser selecionadas, como MarketplaceSubscriptionId.
  • Um conjuntos de dados também tem métricas, que são como funções de agregação em um banco de dados. Por exemplo, NormalizedUsage.
  • Há períodos fixos nos quais os dados podem ser exportados.

Formular uma consulta em um conjuntos de dados

Essas são algumas consultas de exemplo, que mostram como extrair vários tipos de dados.

Consulta Descrição
SELECT MarketplaceSubscriptionId,CustomerId FROM ISVUsage TIMESPAN LAST_MONTH Essa consulta obtém every MarketplaceSubscriptionId e seus correspondentes CustomerId no último mês.
SELECT MarketplaceSubscriptionId, EstimatedExtendedChargeCC FROM ISVUsage ORDER BY EstimatedExtendedChargeCC LIMIT 10 Essa consulta obtém as 10 principais assinaturas em ordem decrescente do número de licenças vendidas em cada assinatura.
SELECT CustomerId, NormalizedUsage, RawUsage FROM ISVUsage WHERE NormalizedUsage > 100000 ORDER BY NormalizedUsage TIMESPAN LAST_6_MONTHS Essa consulta obtém o NormalizedUsage e o RawUsage de todos os clientes que têm NormalizedUsage maior que 100.000.
SELECT MarketplaceSubscriptionId, MonthStartDate, NormalizedUsage FROM ISVUsage WHERE CustomerId IN ('2a31c234-1f4e-4c60-909e-76d234f93161', '80780748-3f9a-11eb-b378-0242ac130002') Essa consulta obtém o MarketplaceSubscriptionId e o uso normalizado para cada mês pelos dois CustomerId valores: 2a31c234-1f4e-4c60-909e-76d234f93161 e 80780748-3f9a-11eb-b378-0242ac130002.

Especificação da consulta

Esta seção descreve a definição e a estrutura da consulta.

Referência de gramática

Esta tabela descreve os símbolos usados em consultas.

Símbolo Significado
? Opcional
* Zero ou mais
+ Um ou mais
| Ou/um da lista

Definição da consulta

A instrução de consulta tem as seguintes cláusulas: SelectClause, FromClause, WhereClause?, OrderClause?, LimitClause? e TimeSpan?.

  • SelectClause: SELECT ColumOrMetricName (, ColumOrMetricName)*
    • ColumOrMetricName: colunas e métricas definidas no conjunto de dados
  • FromClause: FROM DatasetName
    • DataSetName: nome do conjunto de dados definido no dentro do conjunto de dados
  • WhereClause: WHERE FilterCondition (And FilterCondition)*
    • FilterCondition: Valor do operador ColumOrMetricName
      • Operador: = | > | < | >= | <= | != | LIKE | NOT LIKE | IN | NOT IN
      • Valor: Número | Literal de Cadeia de Caracteres | Lista de Números Múltiplos | Lista de Strings Múltiplas
        • Number: -? [0-9]+ (. [0-9] [0-9]*)?
        • StringLiteral: ' [a-zA-Z0-9_]*'
        • MultiNumberList: (Number (,Number)*)
        • MultiStringList: (StringLiteral (,StringLiteral)*)
  • OrderClause: ORDER BY OrderCondition (,OrderCondition)*
    • OrderCondition: ColumOrMetricName (ASC | DESC)*
  • LimitClause: LIMIT [0-9]+
  • TimeSpan: TIMESPAN (HOJE | ONTEM | LAST_7_DAYS | LAST_14_DAYS | LAST_30_DAYS | LAST_90_DAYS | LAST_180_DAYS | LAST_365_DAYS | LAST_MONTH | LAST_3_MONTHS | LAST_6_MONTHS | LAST_1_YEAR)

Estrutura da consulta

Uma Consulta de relatório é constituída de várias partes:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • TIMESPAN

Veja a descrição de cada parte abaixo.

SELECT

Esta parte da consulta especifica as colunas que são exportadas. As colunas que podem ser selecionadas são os campos listados nas seções selectableColumns e availableMetrics de um conjuntos de dados. Se houver uma coluna de métrica incluída na lista de campos selecionada, as métricas serão calculadas para cada combinação distinta das colunas não métricas.

Exemplo:

  • SELECT OfferName, NormalizedUsage

DISTINTO

Adicionar a palavra-chave DISTINCT após SELECT garante que os dados finais exportados não tenham linhas duplicadas. A palavra-chave DISTINCT funciona independentemente de uma coluna de métrica ser selecionada ou não.

Exemplo:

  • SELECIONE DISTINTO MarketplaceSubscriptionId, OfferType

FROM

Essa parte da consulta indica o conjuntos de dados do qual os dados precisam ser exportados. O nome do conjuntos de dados aqui precisa ser um nome de conjuntos de dados válido, retornado pela API de conjuntos de dados.

Exemplo:

  • FROM ISVUsage
  • FROM ISVOrder

WHERE

Essa parte da consulta é usada para especificar condições de filtro no conjunto de dados. Somente as linhas que correspondem a todas as condições listadas nesta cláusula estão presentes no arquivo final exportado. A condição de filtro pode estar em qualquer uma das colunas listadas em selectableColumns e availableMetrics. Os valores especificados na condição de filtro podem ser uma lista de números ou uma lista de cadeias de caracteres somente quando o operador é IN ou NOT IN. Os valores sempre podem ser fornecidos como uma cadeia de caracteres literal e são convertidos nos tipos nativos de colunas. Condições de filtro precisam ser separadas com uma operação AND.

Exemplo:

  • MarketplaceSubscriptionId = '868368da-957d-4959-8992-3c12dc7e6260'
  • CustomerName LIKE '%Contosso%'
  • CustomerId NOT IN (1000, 1001, 1002)
  • OrderQuantity=100
  • OrderQuantity='100'
  • MarketplaceSubscriptionId='7b487ac0-ce12-b732-dcd6-91a1e4e74a50' E CustomerId=' 0f8b7fa0-eb83-a183-1225-ca153ef807aa'

ORDER BY

Esta parte da consulta especifica os critérios de ordenação das linhas exportadas. As colunas nas quais a ordenação pode ser definida precisam ser da selectableColumns e availableMetrics do conjunto de dados. Se não houver nenhuma direção de ordenação especificada, o padrão DESC será na coluna. A ordenação pode ser definida em várias colunas, separando os critérios com uma vírgula.

Exemplo:

  • ORDER BY NormalizedUsage ASC, EstimatedExtendedCharge(CC) DESC
  • ORDER BY CustomerName ASC, NormalizedUsage

LIMIT

Essa parte da consulta especifica o número de linhas exportadas. O número especificado precisa ser um inteiro positivo diferente de zero.

TIMESPAN

Essa parte da consulta especifica o tempo de exportação dos dados. Os valores possíveis devem ser referentes ao campo availableDateRanges na definição do conjunto de valores.

Distinção de maiúsculas e minúsculas na especificação de consulta

A especificação não diferencia maiúsculas de minúsculas. Palavras-chave predefinidas, nomes de coluna e valores podem ser especificados usando letras maiúsculas ou minúsculas.

Confira também