Udostępnij za pośrednictwem

Niestandardowa specyfikacja zapytań dla komercyjnej platformy handlowej

  • Artykuł

Partnerzy mogą używać tej specyfikacji zapytań, aby łatwo sformułować zapytania niestandardowe na potrzeby wyodrębniania danych z tabel analitycznych. Zapytania mogą służyć do wybierania tylko żądanych kolumn i metryk pasujących do określonego kryterium. W centrum specyfikacji języka jest definicja zestawu danych, na której można napisać zapytanie niestandardowe.

Zestawy danych

W ten sam sposób, w jaki niektóre zapytania są uruchamiane względem bazy danych zawierającej tabele i kolumny, zapytanie niestandardowe działa w przypadku zestawów danych, które mają kolumny i metryki. Pełną listę dostępnych zestawów danych do formułowania zapytania można uzyskać przy użyciu interfejsu API zestawów danych.

Oto przykład zestawu danych pokazanego jako kod 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
        }

Części zestawu danych

  • Nazwa zestawu danych jest podobna do nazwy tabeli bazy danych. Na przykład isVUsage. Zestaw danych zawiera listę kolumn, które można wybrać, na przykład MarketplaceSubscriptionId.
  • Zestaw danych zawiera również metryki, które są podobne do funkcji agregacji w bazie danych. Na przykład NormalizedUsage.
  • Istnieją stałe przedziały czasu, w których można eksportować dane.

Formułowanie zapytania w zestawie danych

Oto kilka przykładowych zapytań, które pokazują, jak wyodrębnić różne typy danych.

Query opis
WYBIERZ pozycję MarketplaceSubscriptionId,CustomerId FROM ISVUsage TIMESPAN LAST_MONTH To zapytanie pobiera co MarketplaceSubscriptionId i odpowiadające CustomerId mu w ciągu ostatniego miesiąca.
SELECT MarketplaceSubscriptionId, EstimatedExtendedChargeCC FROM ISVUsage ORDER BY EstimatedExtendedChargeCC LIMIT 10 To zapytanie pobiera 10 pierwszych subskrypcji w kolejności malejącej liczby licencji sprzedanych w ramach każdej subskrypcji.
SELECT CustomerId, NormalizedUsage, RawUsage FROM ISVUsage WHERE NormalizedUsage > 100000 ORDER BY NormalizedUsage TIMESPAN LAST_6_MONTHS To zapytanie pobiera wartość NormalizedUsage i RawUsage wszystkich klientów, którzy mają znormalizowaneusługę większą niż 100 000.
WYBIERZ pozycję MarketplaceSubscriptionId, MonthStartDate, NormalizedUsage FROM ISVUsage WHERE CustomerId IN ('2a31c234-1f4e-4c60-909e-76d234f93161', '80780748-3f9a-11eb-b378-0242ac130002') To zapytanie pobiera wartości MarketplaceSubscriptionId i znormalizowane użycie dla każdego miesiąca według dwóch CustomerId wartości: 2a31c234-1f4e-4c60-909e-76d234f93161 i 80780748-3f9a-11eb-b378-0242ac130002.

Specyfikacja zapytania

W tej sekcji opisano definicję i strukturę zapytania.

Dokumentacja gramatyki

W tej tabeli opisano symbole używane w zapytaniach.

Symbol Znaczenie
? Opcjonalnie
* Zero lub więcej
+ Co najmniej jeden
| Lub/Jedna z listy

Definicja kwerendy

Instrukcja zapytania ma następujące klauzule: SelectClause, FromClause, WhereClause?, OrderClause?, LimitClause?, i TimeSpan?.

  • SelectClause: SELECT ColumOrMetricName (, ColumOrMetricName)*
    • ColumOrMetricName: kolumny i metryki zdefiniowane w zestawie danych
  • FromClause: FROM DatasetName
    • DatasetName: nazwa zestawu danych zdefiniowana w zestawie danych
  • WhereClause: WHERE FilterCondition (AND FilterCondition)*
    • FilterCondition: Wartość operatora ColumOrMetricName
      • Operator: = | > | | > <= | <= | != | LIKE | NIE LUBIĘ | IN | NIE W
      • Wartość: Liczba | StringLiteral | MultiNumberList | MultiStringList
        • Numer: -? [0-9]+ (. [0-9] [0-9]*)?
        • StringLiteral: " [a-zA-Z0-9_]*"
        • MultiNumberList: (Liczba (,Liczba)*)
        • MultiStringList: (StringLiteral (,StringLiteral)*)
  • OrderClause: ORDER BY OrderCondition (,OrderCondition)*
    • OrderCondition: ColumOrMetricName (ASC | DESC)*
  • LimitClause: LIMIT [0-9]+
  • Przedział czasu: PRZEDZIAŁ CZASU ( DZISIAJ | WCZORAJ | 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)

Struktura zapytań

Zapytanie raportu składa się z wielu części:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PRZEDZIAŁ CZASU

Każda część jest opisana poniżej.

SELECT

Ta część zapytania określa kolumny, które są eksportowane. Kolumny, które można wybrać, to pola wymienione w selectableColumns sekcjach zestawu danych i availableMetrics . Jeśli na liście wybranych pól znajduje się kolumna metryki, metryki są obliczane dla każdej odrębnej kombinacji kolumn niemetrycznych.

Przykład:

  • WYBIERZ pozycję OfferName, NormalizedUsage

ODMIENNY

Dodanie słowa kluczowego DISTINCT po wybraniu opcji SELECT gwarantuje, że ostateczne wyeksportowane dane nie mają żadnych zduplikowanych wierszy. Słowo kluczowe DISTINCT działa niezależnie od tego, czy wybrano kolumnę metryki.

Przykład:

  • WYBIERZ POZYCJĘ DISTINCT MarketplaceSubscriptionId, OfferType

FROM

Ta część zapytania wskazuje zestaw danych, z którego należy wyeksportować dane. Podana tutaj nazwa zestawu danych musi być prawidłową nazwą zestawu danych zwracaną przez interfejs API zestawów danych.

Przykład:

  • Z ISVUsage
  • Z ISVOrder

WHERE

Ta część zapytania służy do określania warunków filtrowania w zestawie danych. W ostatnim wyeksportowanym pliku znajdują się tylko wiersze pasujące do wszystkich warunków wymienionych w tej klauzuli. Warunek filtru może znajdować się w dowolnej kolumnie wymienionej w selectableColumns elementach i availableMetrics. Wartości określone w warunku filtru mogą być listą liczb lub listą ciągów tylko wtedy, gdy operator jest IN lub NOT IN. Wartości mogą być zawsze podane jako ciąg literału i są konwertowane na natywne typy kolumn. Należy oddzielić wiele warunków filtrowania za pomocą AND operacji.

Przykład:

  • 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

Ta część zapytania określa kryteria porządkowania wyeksportowanych wierszy. Kolumny, w których można zdefiniować kolejność, muszą pochodzić z selectableColumns zestawu danych i availableMetrics . Jeśli nie określono żadnego kierunku porządkowania, wartość domyślna jest ustawiona DESC na kolumnę. Kolejność można zdefiniować na wielu kolumnach, oddzielając kryteria przecinkami.

Przykład:

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

LIMIT

Ta część zapytania określa liczbę eksportowanych wierszy. Określona liczba musi być dodatnią liczbą całkowitą niezerową.

PRZEDZIAŁ CZASU

Ta część zapytania określa czas trwania, dla którego dane należy wyeksportować. Możliwe wartości powinny pochodzić z availableDateRanges pola w definicji zestawu danych.

Wielkość liter w specyfikacji zapytania

Specyfikacja jest całkowicie niewrażliwa na wielkość liter. Wstępnie zdefiniowane słowa kluczowe, nazwy kolumn i wartości można określić przy użyciu wyższej lub małej litery.

Zobacz też