Partilhar via

Especificação de consulta personalizada para o Microsoft Marketplace

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.

Consulta Descrição
SELECIONEMarketplaceSubscriptionId, CustomerId DE ISVUsage PERÍODO LAST_MONTH Esta consulta obtém todos os MarketplaceSubscriptionId e seus CustomerId correspondentes nos últimos trinta dias.
SELECIONE MarketplaceSubscriptionId, EstimatedExtendedChargeCC DE ISVUsage ORDER POR 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 ÚLTIMOS_6_MESES Esta consulta obtém o NormalizedUsage e o RawUsage de todos os clientes que têm NormalizedUsage superior a 100.000.
SELECIONE MarketplaceSubscriptionId, MonthStartDate, NormalizedUsage DE ISVUsage ONDE CustomerId IN ('aaaabbbb-0000-cccc-1111-dddd2222eeee', 'bbbbcccc-1111-dddd-2222-eeee3333ffff') Esta consulta obtém o MarketplaceSubscriptionId e o uso normalizado para cada mês com base nos dois valores CustomerId: aaaabbbb-0000-cccc-1111-dddd2222eeee e bbbbcccc-1111-dddd-2222-eeee3333ffff.

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 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 dentro do conjunto de dados
  • WhereClause: ONDE 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: ColumnOrMetricName (ASC | DESC)*
  • LimitClause: LIMIT [0-9]+
  • TimeSpan: TIMESPAN ( HOJE | ONTEM | ÚLTIMOS_7_DIAS | ÚLTIMOS_14_DIAS | ÚLTIMOS_30_DIAS | ÚLTIMOS_90_DIAS | ÚLTIMOS_180_DIAS | ÚLTIMOS_365_DIAS | MÊS_PASSADO | ÚLTIMOS_3_MESES | ÚLTIMOS_6_MESES | ÚLTIMO_ANO)

Estrutura da consulta

Uma consulta Relatório é composta por várias partes:

  • SELECT
  • DE
  • ONDE
  • ORDENAR POR
  • LIMITE
  • PERÍODO DE TEMPO

Cada parte é descrita 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 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:

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

Exemplo:

  • SELECIONAR DISTINTOSMarketplaceSubscriptionId, OfferType

DE

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

ONDE

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 estiver 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 operação 'AND'.

Exemplo:

  • MarketplaceSubscriptionId = 'aaaabbbb-0000-cccc-1111-dddd2222eeee'
  • CustomerName GOSTO '%Contosso%'
  • CustomerId NÃO EXISTE EM (1000, 1001, 1002)
  • QuantidadeEncomenda=100
  • QuantidadeDePedido='100'
  • MarketplaceSubscriptionId='bbbbcccc-1111-dddd-2222-eeee3333ffff' E CustomerId='0f8b7fa0-eb83-a183-1225-ca153ef807aa'

ORDENAR POR

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

Exemplo:

  • ENCOMENDAR POR ASC NormalizedUsage, EstimatedExtendedCharge(CC) DESC
  • ORDENAR POR NomeDoCliente ASC, UsoNormalizado

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 campo availableDateRanges na definição do conjunto de dados.

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

A especificação é completamente insensível a maiúsculas e minúsculas. Palavras-chave, nomes de colunas e valores predefinidos podem ser especificados usando maiúsculas ou minúsculas.

Ver também

  • Last updated on