Partager via

Spécification de requête personnalisée pour la Place de marché commerciale

  • Article

Les partenaires peuvent utiliser cette spécification de requête pour facilement formuler des requêtes personnalisées à des fins d’extraction de données à partir de tables analytiques. Les requêtes peuvent être utilisées pour sélectionner uniquement les colonnes et les métriques souhaitées correspondant à un critère spécifique. La spécification du langage repose sur la définition du jeu de données sur laquelle une requête personnalisée peut être écrite.

Groupes de données

De la même façon que certaines requêtes sont exécutées sur une base de données dotée de tables et de colonnes, une requête personnalisée fonctionne sur des jeux de données dotés de colonnes et de métriques. La liste complète des jeux de données disponibles pour formuler une requête peut être obtenue à l’aide de l’API des jeux de données.

Voici un exemple de jeu de données présenté sous la forme d’un 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
        }

Parties d’un jeu de données

  • Un nom de jeu de données est similaire à un nom de table de base de données. Par exemple, ISVUsage. Un jeu de données contient une liste de colonnes qui peuvent être sélectionnées, par exemple MarketplaceSubscriptionId.
  • Un jeu de données possède également des métriques, qui s’apparentent aux fonctions d’agrégation d’une base de données. Par exemple, NormalizedUsage.
  • Il existe des intervalles de temps fixes au cours desquels les données peuvent être exportées.

Formulation d’une requête sur un jeu de données

Voici quelques exemples de requêtes illustrant comment extraire différents types de données.

Requête Description
SELECT MarketplaceSubscriptionId,CustomerId FROM ISVUsage TIMESPAN LAST_MONTH Cette requête obtient toutes et MarketplaceSubscriptionId ses correspondances CustomerId au cours du dernier mois.
SELECT MarketplaceSubscriptionId, EstimatedExtendedChargeCC FROM ISVUsage ORDER BY EstimatedExtendedChargeCC LIMIT 10 Cette requête obtient les 10 premiers abonnements dans l’ordre décroissant du nombre de licences vendues sous chaque abonnement.
SELECT CustomerId, NormalizedUsage, RawUsage FROM ISVUsage WHERE NormalizedUsage > 100000 ORDER BY NormalizedUsage TIMESPAN LAST_6_MONTHS Cette requête obtient la normalizedUsage et RawUsage de tous les clients qui ont NormalizedUsage supérieur à 100 000.
SELECT MarketplaceSubscriptionId, MonthStartDate, NormalizedUsage FROM ISVUsage WHERE CustomerId IN ('2a31c234-1f4e-4c60-909e-76d234f93161', '80780748-3f9a-11eb-b378-0242ac130002') Cette requête obtient l’utilisation MarketplaceSubscriptionId normalisée pour chaque mois par les deux CustomerId valeurs : 2a31c234-1f4e-4c60-909e-76d234f93161 et 80780748-3f9a-11eb-b378-0242ac130002.

Spécification de requête

Cette section décrit la définition et la structure de la requête.

Référence de grammaire

Ce tableau décrit les symboles utilisés dans les requêtes.

Symbole Signification
? Facultatif
* Zéro ou plus
+ Un ou plus
| Ou/Un des éléments de la liste

Définition de la requête

L’instruction de requête contient les clauses suivantes : SelectClause, FromClause, WhereClause?, OrderClause?, LimitClause?, and TimeSpan?.

  • SelectClause : SELECT ColumOrMetricName (, ColumOrMetricName)*
    • ColumOrMetricName : colonnes et métriques définies dans le jeu de données
  • FromClause : FROM DatasetName
    • DatasetName: nom du jeu de données défini dans le jeu de données
  • WhereClause : WHERE FilterCondition (AND FilterCondition)*
    • FilterCondition : Valeur de l’opérateur ColumOrMetricName
      • Operator: = | > | < | >= | <= | != | LIKE | NOT LIKE | IN | NOT IN
      • Valeur : Nombre | StringLiteral | MultiNumberList | MultiStringList
        • Nombre : -? [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 ( AUJOURD’HUI | HIER | 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)

Structure de la requête

Une requête de rapport est composée de plusieurs parties :

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

Chaque partie est décrite ci-dessous.

SELECT

Cette partie de la requête spécifie les colonnes qui sont exportées. Les colonnes pouvant être sélectionnées correspondent aux champs répertoriés dans les sections selectableColumns et availableMetrics d’un jeu de données. S’il existe une colonne de métrique incluse dans la liste de champs sélectionnée, les métriques sont calculées pour chaque combinaison distincte des colonnes non paramétrables.

Exemple :

  • SELECT OfferName, NormalizedUsage

DISTINCT

L’ajout d’un mot clé DISTINCT après SELECT garantit que les données exportées finales n’ont pas de lignes en double. Le mot clé DISTINCT fonctionne indépendamment du fait qu’une colonne métrique soit sélectionnée ou non.

Exemple :

  • SELECT DISTINCT MarketplaceSubscriptionId, OfferType

FROM

Cette partie de la requête indique le jeu de données à partir duquel les données doivent être exportées. Le nom du jeu de données spécifié ici doit correspondre à un nom de jeu de données valide renvoyé par l’API des jeux de données.

Exemple :

  • FROM ISVUsage
  • FROM ISVOrder

WHERE

Cette partie de la requête est utilisée pour spécifier les conditions de filtre du jeu de données. Seules les lignes correspondant à toutes les conditions répertoriées dans cette clause sont présentes dans le fichier exporté final. La condition de filtre peut se trouver dans l’une des colonnes répertoriées dans selectableColumns et availableMetrics. Les valeurs spécifiées dans la condition de filtre peuvent correspondre à une liste de nombres ou une liste de chaînes uniquement lorsque l’opérateur est IN ou NOT IN. Les valeurs peuvent toujours être fournies sous forme de chaîne littérale et sont converties en types natifs de colonnes. Plusieurs conditions de filtre doivent être séparées par une opération AND.

Exemple :

  • 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

Cette partie de la requête spécifie les critères de tri des lignes exportées. Les colonnes sur lesquelles le tri peut être défini doivent provenir de selectableColumns et availableMetrics du jeu de données. Si aucune direction de classement n’est spécifiée, elle est définie DESC par défaut sur la colonne. Le tri peut être défini sur plusieurs colonnes en séparant les critères par une virgule.

Exemple :

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

LIMIT

Cette partie de la requête spécifie le nombre de lignes exportées. Le nombre que vous spécifiez doit être un entier positif non nul.

TIMESPAN

Cette partie de la requête spécifie la durée pendant laquelle les données doivent être exportées. Les valeurs possibles doivent provenir du champ availableDateRanges dans la définition du jeu de données.

Respect de la casse dans la spécification de requête

La spécification ne respecte pas la casse. Les mots clés prédéfinis, les noms de colonnes et les valeurs peuvent être spécifiés en majuscules ou en minuscules.

Voir aussi