Compartir a través de

Especificación de consulta personalizada: Api de aplicaciones y juegos

Los asociados pueden usar esta especificación de consulta para formular fácilmente consultas personalizadas para extraer datos de las tablas de análisis. Las consultas se pueden usar para seleccionar solo las columnas deseadas y las métricas que coincidan con un determinado criterio. En el centro de la especificación del lenguaje se encuentra la definición del conjunto de datos sobre el que se puede escribir una consulta personalizada.

Conjuntos de datos

Del mismo modo que algunas consultas se ejecutan en una base de datos que tiene tablas y columnas, una consulta personalizada funciona en conjuntos de datos que tienen columnas y métricas. La lista completa de los conjuntos de datos disponibles para formular una consulta puede obtenerse mediante la API de conjuntos de datos.

Este es un ejemplo de un conjunto de datos que se muestra como JSON.

{ 
                            "datasetName": "Acquisitions", 
                            "selectableColumns": [ 
                                "TitleId", 
                                "ProductId", 
                                "XboxProductId", 
                                "ProductTypeName", 
                                "TitleName", 
                                "CatalogId", 
                                "SandboxId", 
                                "SkuId", 
                                "SkuTypeName", 
                                "SkuDisplayName", 
                                "AvailabilityId", 
                                "RegionName", 
                                "CountryName", 
                                "Market", 
                                "PaymentType", 
                                "StoreClientName", 
                                "StoreClientCategory", 
                                "ParentProductName", 
                                "ParentProductId", 
                                "XboxParentProductId", 
                                "AcquisitionType", 
                                "PurchaseTaxType", 
                                "LocalCurrencyCode", 
                                "SupportedPlatform", 
                                "Age", 
                                "Gender", 
                                "OsVersion", 
                                "DeviceType", 
                                "DateStamp" 
                            ], 
                            "availableMetrics": [ 
                                "PurchaseQuantity", 
                                "PurchasePriceUSDAmount", 
                                "PurchaseTaxUSDAmount", 
                                "PurchasePriceLocalAmount", 
                                "PurchaseTaxLocalAmount" 
                            ], 
                            "availableDateRanges": [ 
                                "LAST_72_HOURS", 
                                "LAST_30_DAYS", 
                                "LAST_3_MONTHS", 
                                "LAST_6_MONTHS", 
                                "LAST_12_MONTHS", 
                                "LAST_2_YEARS", 
                                "LAST_3_YEARS", 
                                "LAST_4_YEARS" 
                            ], 
                            "columnFilters": {}, 
                            "aggregationToDateRangeMapping": { 
                                "Hourly": "LAST_72_HOURS", 
                                "Daily": "LAST_30_DAYS,LAST_3_MONTHS", 
                                "Weekly": "LAST_6_MONTHS,LAST_12_MONTHS", 
                                "Monthly": "LAST_2_YEARS,LAST_3_YEARS,LAST_4_YEARS" 
                            }, 
                        }

Elementos de un conjunto de datos

Un nombre de conjunto de datos es como el nombre de una tabla de base de datos. Por ejemplo, Acquisitions. Un conjunto de datos tiene una lista de columnas que se pueden seleccionar, como AcquisitionType.

Un conjunto de datos también tiene métricas, que son como funciones de agregación en una base de datos. Por ejemplo, PurchaseQuantity.

Hay intervalos de tiempo fijos durante los que se pueden exportar los datos.

Formulación de una consulta en un conjunto de datos

A continuación se muestran consultas de ejemplo que muestran cómo extraer varios tipos de datos.

Consultar Descripción
SELECT AcquisitionType, ProductId FROM Acquisitions TIMESPAN LAST_3_MONTHS Esta consulta obtiene cada AcquisitionType y su productId correspondiente en los últimos tres meses.
SELECT ProductId, PurchaseQuantity FROM Acquisitions ORDER BY LIMIT PurchaseQuantity 10 Esta consulta obtiene los 10 productos principales en orden decreciente de su cantidad de compra.

Especificación de consulta

En esta sección se describe la definición y la estructura de la consulta.

Referencia de gramática

En esta tabla se describen los símbolos que se usan en las consultas.

Símbolo Significado
? Opcionales
* Cero o más
+ Uno o más
| O/Uno de la lista

Definición de la consulta

La instrucción query tiene las siguientes cláusulas: SelectClause, FromClause, WhereClause?, OrderClause?, LimitClause?y TimeSpan?.

  • SelectClause: SELECT ColumOrMetricName (, ColumOrMetricName)*
    • ColumOrMetricName: columnas y métricas definidas en el conjunto de datos
  • FromClause: FROM DatasetName
    • DatasetName: nombre del conjunto de datos definido en el conjunto de datos
  • WhereClause: WHERE FilterCondition (**AND** FilterCondition)*
    • FilterCondition: ColumOrMetricName Operator Value
      • Operador: = | > | < | >= | <= | != | LIKE | NOT LIKE | IN | NOT IN
      • Valor: Number | StringLiteral | MultiNumberList | MultiStringList
        • Número: -? [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 ( TODAY | YESTERDAY | 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)

Estructura de la consulta

Una consulta de informe se compone de varios elementos:

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

Cada parte se describe de la manera siguiente:

SELECT

Esta parte de la consulta especifica las columnas que se exportan. Las columnas que se pueden seleccionar son los campos enumerados en las secciones selectableColumns y availableMetrics de un conjunto de datos. Si hay una columna de métrica incluida en la lista de campos seleccionada, las métricas se calculan para cada combinación distinta de las columnas no métricas.

Ejemplo:

  • ESCOGER ProductId, PurchaseQuantity

DISTINCT

Agregar la palabra clave DISTINCT después de SELECT garantiza que los datos exportados finales no tengan filas duplicadas. La palabra clave DISTINCT funciona independientemente de si se selecciona una columna de métrica.

Ejemplo:

  • SELECT DISTINCT ProductId, PurchaseQuantity

FROM

Este elemento de la consulta indica el conjunto de datos desde el que se deben exportar los datos. El nombre del conjunto de datos que se proporciona aquí debe ser un nombre de conjunto de datos válido devuelto por la API de los conjuntos de datos.

Ejemplo:

  • DE Acquisition
  • DE Usage

WHERE

Este elemento de la consulta se usa para especificar las condiciones de filtro en el conjunto de datos. Solo las filas que coinciden con todas las condiciones enumeradas en esta cláusula están presentes en el archivo exportado final. La condición de filtro puede estar en cualquiera de las columnas enumeradas en selectableColumns y availableMetrics. Los valores especificados en la condición de filtro pueden ser una lista de números o una lista de cadenas solo cuando el operador es IN o NOT IN. Los valores siempre se pueden proporcionar como una cadena literal y se convierten en los tipos nativos de columnas. Se deben separar varias condiciones de filtro con una operación AND.

Ejemplo:

  • DÓNDE ProductId = '8da-86836-3c12dc7e62957d-4959-899260'
  • WHERE TitleName LIKE '%Grand%'
  • DÓNDE CountryName NO ESTÁ (3243, 321, 2123)
  • DÓNDE PurchaseQuantity =100
  • DÓNDE PurchaseQuantity ='100'
  • DÓNDE ProductId ='7b487ac0-ce12-b732-dcd6-91a1e4e74a50' Y CountryName =' Canada'

ORDER BY

En este elemento de la consulta se especifican los criterios de ordenación de las filas exportadas. Las columnas en las que se puede definir la ordenación deben ser de selectableColumns y availableMetrics del conjunto de datos. Si no se especifica ninguna dirección de ordenación, se usa DESC de forma predeterminada en la columna. La ordenación se puede definir en varias columnas separando los criterios con una coma.

Ejemplo:

  • ORDER BY PurchaseQuantity ASC, TitleName (CC) DESC
  • ORDER BY TitleName ASC, PurchaseQuantity

LIMIT

Esta parte de la consulta especifica el número de filas que se exportan. El número que especifique debe ser un entero positivo distinto de cero.

TIMESPAN

Este elemento de la consulta especifica el período de tiempo durante el que se deben exportar los datos. Los valores posibles deben ser del campo availableDateRanges de la definición del conjunto de datos.

Distinción de mayúsculas y minúsculas en la especificación de consultas

La especificación no distingue entre mayúsculas y minúsculas. Las palabras clave predefinidas, los nombres de columna y los valores se pueden especificar con mayúsculas o minúsculas.

Ejemplo de consulta personalizada

curl --location 'https://manage.devcenter.microsoft.com/consumer/insights/v1.1/ScheduledReport' \ 
 --header 'Authorization: \ 
 --header 'Content-Type: application/json' \ 
 --data '{ 
 "Description": "Testing sample report", 
 "QueryId": "<id of the query>", 
 "ReportName": "Test Reports", 
 "executeNow": true, 
 "QueryStartTime": "2024-06-01", 
 "QueryEndTime": "2024-06-13" 
 }'

El intervalo de fechas proporcionado debe cumplir la asignación de fecha a agregación del conjunto de datos. Por ejemplo, si "last_30_days" se asigna a la agregación diaria y se especifica un intervalo de fechas personalizado que supera los 30 días con la agregación diaria, se producirá un error que indica que la agregación diaria no es compatible con este intervalo de fechas. Del mismo modo, si "last_3_months" se asigna a la agregación semanal, para una diferencia de intervalo de fechas entre 31 y 90 días, se debe usar la agregación semanal.