Partilhar via

Especificação de consulta personalizada para mercado 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 correspondam a um determinado critério. No centro da especificação da linguagem está a definição do conjunto de dados na qual uma consulta personalizada pode ser escrita.

Conjuntos de Dados

Da mesma forma que algumas consultas são executadas 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 obtida 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 conjunto de dados é como um nome de tabela de banco de dados. Por exemplo, ISVUsage. Um conjunto de dados tem uma lista de colunas que podem ser selecionadas, como MarketplaceSubscriptionId.
  • Um conjunto de dados também tem métricas, que são como funções de agregação em um banco de dados. Por exemplo, NormalizedUsage.
  • Existem períodos de tempo fixos durante os quais os dados podem ser exportados.

Formulando uma consulta em um conjunto de dados

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

Query Description
SELECT MarketplaceSubscriptionId,CustomerId FROM ISVUsage TIMESPAN LAST_MONTH Esta consulta obtém todos os MarketplaceSubscriptionId correspondentes CustomerId no último mês.
SELECT MarketplaceSubscriptionId, EstimatedExtendedChargeCC FROM ISVUsage ORDER BY EstimatedExtendedChargeCC LIMIT 10 Esta consulta obtém as 10 principais subscrições por ordem decrescente do número de licenças vendidas ao abrigo de cada subscrição.
SELECT CustomerId, NormalizedUsage, RawUsage FROM ISVUsage WHERE NormalizedUsage > 100000 ORDER BY NormalizedUsage TIMESPAN LAST_6_MONTHS Esta consulta obtém o NormalizedUsage e 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') Esta 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 gramatical

Esta tabela descreve os símbolos usados nas consultas.

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

Definição de consulta

A instrução query 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 dentro do Dataset
  • WhereClause: WHERE FilterCondition (E FilterCondition)*
    • FilterCondition: Valor do operador ColumOrMetricName
      • Operador: = | > | < | >= | <= | != | GOSTAR | NÃO GOSTO | EM | NÃO EM
      • Valor: Número | StringLiteral | Lista de Múltiplos Números | MultiStringList
        • Número: -? [0-9]+ (. [0-9] [0-9]*)?
        • StringLiteral: ' [a-zA-Z0-9_]*'
        • MultiNumberList: (Número (,Número)*)
        • 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 Relatório é composta por várias partes:

  • SELECIONAR
  • FROM
  • WHERE
  • ORDER BY
  • LIMITE
  • PERÍODO DE TEMPO

Cada parte é descrita abaixo.

SELECIONAR

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

Exemplo:

  • SELECIONAR OfferName, NormalizedUsage

DISTINTOS

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 métrica estar ou não selecionada.

Exemplo:

  • SELECIONAR DISTINTO MarketplaceSubscriptionId, OfferType

FROM

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

Exemplo:

  • DE ISVUsage
  • DE ISVOrder

WHERE

Esta parte da consulta é usada para especificar condições de filtro no conjunto de dados. Apenas as linhas correspondentes a todas as condições listadas nesta cláusula estão presentes no arquivo final exportado. A condição do 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 dados como uma cadeia de caracteres literal e são convertidos para os tipos nativos de colunas. Várias condições de filtro precisam ser separadas com uma AND operação.

Exemplo:

  • MarketplaceSubscriptionId = '868368da-957d-4959-8992-3c12dc7e6260'
  • CustomerName LIKE '%Contosso%'
  • CustomerId NÃO DENTRO (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 para as linhas exportadas. As colunas nas quais a selectableColumns ordenação pode ser definida precisam ser do e availableMetrics do conjunto de dados. Se não houver nenhuma direção de ordenação especificada, ela será padronizada na DESC coluna. A ordenação pode ser definida em várias colunas separando os critérios com uma vírgula.

Exemplo:

  • ORDEM POR NormalizedUsage ASC, EstimatedExtendedCharge(CC) DESC
  • ENCOMENDAR POR CustomerName ASC, NormalizedUsage

LIMITE

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

PERÍODO DE TEMPO

Esta parte da consulta especifica a duração do tempo durante o qual os dados precisam ser exportados. Os valores possíveis devem ser do availableDateRanges campo na definição do conjunto de dados.

Diferenciação de maiúsculas e minúsculas na especificação de

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

Consulte também