Udostępnij za pośrednictwem

Niestandardowa specyfikacja zapytań dla komercyjnej platformy handlowej

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.

Zbiory 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.

Zapytanie Opis
WYBRAĆ MarketplaceSubscriptionId,CustomerId FROM ISVUsage TIMESPAN LAST_MONTH To zapytanie pobiera każdy MarketplaceSubscriptionId i odpowiadający mu CustomerId na przestrzeni ostatniego miesiąca.
WYBRAĆ MarketplaceSubscriptionId, EstimatedExtendedChargeCC OD 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.
WYBRAĆ CustomerId, NormalizedUsage, RawUsage FROM ISVUsage WHERE NormalizedUsage > 100000 ORDER BY NormalizedUsage TIMESPART LAST_6_MONTHS To zapytanie pobiera NormalizedUsage i RawUsage wszystkich klientów, którzy mają znormalizowane użycie większe niż 100 000.
SELECT MarketplaceSubscriptionId, MonthStartDate, NormalizedUsage FROM ISVUsage WHERE CustomerId IN ('aaaabb-0000-cccc-1111-dddd2222ee', 'bbbbcccc-111-ddddd-2222-ee3333ffff') To zapytanie pobiera MarketplaceSubscriptionId oraz znormalizowane użycie dla każdego miesiąca przy użyciu dwóch wartości CustomerId: aaaabbbb-0000-cccc-1111-dddd2222eeee i bbbbcccc-1111-dddd-2222-eeee3333ffff.

Specyfikacja zapytania

W tej sekcji opisano definicję i strukturę zapytania.

Kompendium gramatyki

W tej tabeli opisano symbole używane w zapytaniach.

Symbol Znaczenie
? Fakultatywny
* Zero lub więcej
+ Co najmniej jeden
| Albo/Jedna pozycja 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 NazwaZestawu danych
    • DatasetName: nazwa zestawu danych zdefiniowana w zestawie danych
  • WhereClause: WHERE FilterCondition (AND FilterCondition)*
    • FilterCondition: Wartość operatora ColumOrMetricName
      • operator: = | > | < | >= | <= | != | LIKE | NOT LIKE | IN | NOT IN
      • wartość: Liczba | StringLiteral | MultiNumberList | MultiStringList
        • Numer: -? [0-9]+ (. [0-9] [0-9]*)?
        • StringLiteral: " [a-zA-Z0-9_]*"
        • MultiNumberList: (Liczba (,Liczba)*)
        • MultiStringList: (StringLiteral (,StringLiteral)*)
  • Klauzula zamówienia: ORDER BY OrderCondition (,OrderCondition)*
    • Warunek zamówienia: ColumOrMetricName (ASC | DESC)*
  • LimitClause: LIMIT [0–9]+
  • timeSpan: TIMESPAN ( 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:

  • WYBIERZ
  • Z
  • GDZIE
  • SORTUJ WEDŁUG
  • OGRANICZAĆ
  • PRZEDZIAŁ CZASU

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

WYBIERZ

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

Przykład:

  • WYBIERZ,OfferNameNormalizedUsage

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 DISTINCTMarketplaceSubscriptionId, OfferType

Z

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

GDZIE

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 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ą zawsze być podane jako ciąg znaków i są konwertowane na natywne typy kolumn. Należy oddzielić wiele warunków filtrowania za pomocą operacji AND.

Przykład:

  • MarketplaceSubscriptionId = "aaaabbbb-0000-cccc-1111-dddd2222eeee"
  • CustomerName LIKE "%Contosso%"
  • CustomerId NOT IN (1000, 1001, 1002)
  • IlośćZamówienia=100
  • IlośćZamówienia='100'
  • MarketplaceSubscriptionId='bbbbcccc-1111-dddd-2222-eeee333ffff' AND CustomerId='0f8b7fa0-eb83-a183-1225-ca153ef807aa'

SORTUJ WEDŁUG

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

Przykład:

  • SORTUJ WEDŁUG ZnormalizowaneUżycie ROSNĄCO, SzacowanyPrzedłużonyŁadunek(CC) MALEJĄCO
  • SORTUJ WEDŁUG NazwaKlienta ROSNĄCO, ZnormalizowaneUżycie

OGRANICZAĆ

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 pola availableDateRanges w definicji zestawu danych.

Czułość na 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ż