Поделиться через

Спецификация пользовательского запроса для коммерческой платформы

  • Статья

Партнеры могут использовать эту спецификацию запроса, чтобы легко формировать пользовательские запросы на извлечение данных из таблиц аналитики. Запросы можно использовать для выбора только нужных столбцов и метрик, соответствующих определенному условию. В основе спецификации языка лежит определение набора данных, по которому можно написать пользовательский запрос.

Наборы данных

Так же как некоторые запросы выполняются для базы данных, которая содержит таблицы и столбцы, пользовательский запрос работает с наборами, состоящими из столбцов и метрик. Полный список доступных наборов данных для составления запросов можно получить с помощью API наборов данных.

Ниже приведен пример набора данных, показанного как 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
        }

Части набора данных

  • Имя набора данных похоже на имя таблицы в базе данных. Например, ISVUsage. Набор данных содержит список столбцов, которые можно выбрать, например MarketplaceSubscriptionId.
  • Набор данных также имеет метрики, которые подобны статистическим функциям в базе данных. Например, NormalizedUsage.
  • Существуют фиксированные интервалы времени, в течение которых можно экспортировать данные.

Составление запроса по набору данных

Ниже приведены примеры запросов, извлекающих различные типы данных.

Query Description
SELECT MarketplaceSubscriptionId,CustomerId FROM ISVUsage TIMESPAN LAST_MONTH Этот запрос получает каждый MarketplaceSubscriptionId и соответствующий CustomerId за последний месяц.
SELECT MarketplaceSubscriptionId, EstimatedExtendedChargeCC FROM ISVUsage ORDER BY EstimatedExtendedChargeCC LIMIT 10 Этот запрос получает первые 10 подписок в порядке уменьшения количества лицензий, проданных в каждой подписке.
SELECT CustomerId, NormalizedUsage, RawUsage FROM ISVUsage WHERE NormalizedUsage > 100000 ORDER BY NormalizedUsage TIMESPAN LAST_6_MONTHS Этот запрос получает нормализованный и rawUsage всех клиентов, которые нормализованыUsage больше 100 000.
SELECT MarketplaceSubscriptionId, MonthStartDate, NormalizedUsage FROM ISVUsage WHERE CustomerId IN ('2a31c234-1f4e-4c60-909e-76d234f93161", '80780748-3f9a-11eb-b378-0242ac130002') Этот запрос получает MarketplaceSubscriptionId нормализованное использование для каждого месяца двумя CustomerId значениями: 2a31c234-1f4e-4c60-909e-76d234f93161 и 80780748-3f9a-11eb-b378-0242ac130002.

Спецификация запроса

В этом разделе описывается определение и структура запроса.

Справочник по грамматике

В этой таблице дано описание символов, используемых в запросах.

Символ Значение
? Необязательно
* Ноль или более
+ Один центр обработки данных
| Или один из списка

Определение запроса

Оператор запроса содержит следующие предложения: SelectClause, FromClause, WhereClause?, OrderClause?, LimitClause? и TimeSpan?.

  • SelectClause: SELECT ColumOrMetricName (, ColumOrMetricName)*
    • ColumOrMetricName: столбцы и метрики, которые определены в наборе данных
  • FromClause: FROM DatasetName
    • DatasetName: имя набора данных, которое определено в наборе данных
  • WhereClause: WHERE FilterCondition (AND FilterCondition)*
    • FilterCondition: Значение оператора ColumOrMetricName
      • Оператор: = | > | | > <= | <= | != | | LIKE | НЕ НРАВИТСЯ | IN | НЕ В
      • Значение: число | StringLiteral | MultiNumberList | MultiStringList
        • 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 (СЕГОДНЯ | ВЧЕРА | 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)

Структура запроса

Запрос отчета состоит из нескольких частей:

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

Каждая часть описана ниже.

SELECT

Эта часть запроса указывает столбцы, экспортированные. Столбцы, которые могут быть выбраны, являются полями, перечисленными в разделах selectableColumns и availableMetrics набора данных. Если в списке выбранных полей есть столбец метрик, то метрики вычисляются для каждого отдельного сочетания столбцов, не являющихся метриками.

Пример:

  • SELECT OfferName, NormalizedUsage

DISTINCT

Добавление ключевого слова DISTINCT после SELECT гарантирует, что окончательные экспортированные данные не имеют повторяющихся строк. Ключевое слово DISTINCT действует независимо от того, выбран ли столбец метрик или нет.

Пример:

  • SELECT DISTINCT MarketplaceSubscriptionId, OfferType

FROM

Эта часть запроса определяет набор данных, из которого необходимо экспортировать данные. Имя набора данных, указанное здесь, должно быть допустимым именем набора данных, возвращаемым API наборов данных.

Пример:

  • FROM ISVUsage
  • FROM ISVOrder

WHERE

Эта часть запроса используется для указания условий фильтра для набора данных. В окончательно экспортируемом файле присутствуют только строки, соответствующие всем условиям, указанным в этом предложении. Условие фильтра может находиться в любом из столбцов, перечисленных в selectableColumns и availableMetrics. Значения, указанные в условии фильтра, могут представлять собой список чисел или список строк только в том случае, если оператор имеет значение IN или NOT IN. Значения всегда могут быть заданы в виде литеральной строки, и они преобразуются в собственные типы столбцов. Несколько условий фильтра должны быть разделены оператором AND.

Пример:

  • 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' AND CustomerId=' 0f8b7fa0-eb83-a183-1225-ca153ef807aa'

ORDER BY

В этой части запроса указываются критерии упорядочивания для экспортируемых строк. Столбцы, для которых может быть определен порядок сортировки, должны находиться в разделах selectableColumns и availableMetrics набора данных. Если упорядочения нет указанного направления, он по умолчанию используется DESC для столбца. Упорядочивание можно определить по нескольким столбцам, разделяя критерий запятой.

Пример:

  • ORDER BY NormalizedUsage ASC, EstimatedExtendedCharge(CC) DESC
  • ORDER BY Имя_заказчика ASC, NormalizedUsage

LIMIT

Эта часть запроса указывает количество экспортируемых строк. Указанное число должно быть положительным ненулевым целым числом.

TIMESPAN

В этой части запроса указывается период времени, в течение которого необходимо экспортировать данные. Возможные значения должны быть из поля availableDateRanges в определении набора данных.

Чувствительность к регистру в спецификации запроса

Регистр символов в спецификации полностью игнорируется. Предопределенные ключевые слова, имена и значения столбцов можно указывать с помощью прописных и строчных символов.

См. также