Guía para desarrolladores sobre el lenguaje de consulta para publicadores (PQL)

Sintaxis y uso de PQL

PQL es un lenguaje similar a SQL para consultar objetos. La sintaxis de PQL es similar al de SQL, con algunas diferencias descritas aquí. Esta sección describe la sintaxis de PQL y cómo usarla para filtrar varios tipos de objetos.

La sintaxis de PQL se puede resumir de la siguiente manera:

[WHERE <condition> {[AND | OR] <condition> ...}]
[ORDER BY <property> [ASC | DESC]]
[LIMIT {[<offset>,] <count>} | {<count> OFFSET <offset>}]

<condition> := <property> { = | != } <value>
<condition> := <property> { = | != } <bind variable>
<condition> := <property> IN <list>
<condition> := NOT <property> IN <list>
<condition> := <property> LIKE <wildcard%match>
<condition> := <property> IS NULL
<bind variable> := :<name>

Notas

  • Las palabras clave de PQL no distinguen mayúsculas de minúsculas.
  • Las strings se escapan automáticamente cuando se usan en parámetros de vinculación. De lo contrario, haz lo siguiente:

    • Para una cadena entre comillas simples (apóstrofos), escape cualquier apóstrofo adicional escribiéndolo como un par de comillas simples.

      Ejemplo: "WHERE name = 'Company''s name'".

Palabras clave (no distingue mayúsculas de minúsculas)

  • WHERE: Expresa un conjunto de cero o más condiciones. unidas opcionalmente con frases OR o Y. Puedes agrupar las frases OR o AND con paréntesis. Ejecutando la consulta "" (vacío) string) muestra todo.

    Ejemplos: WHERE width = 728
    WHERE width = 728 AND height = 90
    WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)

  • OR: Une varias condiciones, de las cuales solo se debe realizar una ser cierto. Si quieres comprobar cualquiera de los diversos valores de una sola considera usar una cláusula IN.

    Ejemplo: WHERE width = 728 OR height = 90.

  • AND: Une varias condiciones que deben cumplirse satisfechos con la cláusula AND.

    Ejemplo: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB').

  • ORDER BY: ordena los resultados mostrados en ascendente (ASC, donde "A" es el primero) o descendente (DESC, donde “A” es el último) orden. Si la dirección no es especificado, el valor predeterminado es ASC. Si no se incluye esta cláusula el valor predeterminado es ASC en el primer campo.

    Ejemplo: WHERE id IN (5008, 8745, 3487) ORDER BY id.

  • LIMIT: Es la cantidad de resultados que se mostrarán. El LIMIT también puede incluir un <offset>, que es cuántas filas desde el inicio para desplazar el conjunto de resultados.

    Ejemplos (ambos ejemplos muestran el mismo conjunto de resultados):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
    WHERE type = 'AGENCY' LIMIT 50,50

  • OFFSET: Es el desplazamiento hacia el conjunto de resultados inicial. que devuelven valores. Usa esta opción para desplazarte por los resultados.

    Ejemplo (muestra resultados 51 a 100):
    WHERE type = 'AGENCY' LIMIT 50 OFFSET 50

  • <property>: Una de las propiedades expuestas por el . Cada objeto expone diferentes propiedades por las que puedes filtrar, usando PQL; por lo general, no puedes filtrar todas las propiedades que admite una así que revisa la siguiente lista para ver qué propiedades admiten consultas de PQL. Por ejemplo, las propiedades de creatividades por las que puedes filtrar incluyen id, name, width y height.
  • <value>: Los valores de string deben estar entrecomillados con un comillas simples ('). Los valores numéricos pueden estar entre comillas o no. Comodines no son compatibles.
  • IN: Compara el valor de una propiedad con cada elemento de una enumerar; si alguno coincide, es positiva. El IN equivale a muchas consultas =, una para cada valor, que están unidas por OR. Los valores se especifican como una lista separada por comas de valores, encerrados entre paréntesis: (a, b, c). Todos los valores de la lista y cómo se evalúa.

    Ejemplo: WHERE name IN ('CompanyNameA', 'CompanyNameB').

  • NOT IN: Compara el valor de una propiedad con cada elemento. en una lista; si no hay coincidencia, es positiva. El NOT IN equivale a muchas consultas !=, una para cada valor, que están unidas por OR. Los valores se especifican como una lista separada por comas de valores, encerrados entre paréntesis: (a, b, c). Todos los valores de la lista y cómo se evalúa.

    Ejemplo: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB').

  • LIKE: Te permite buscar objetos con comodines. la coincidencia de cadenas. El signo de porcentaje (%) representa cero, uno o varios caracteres. Usa un par para encerrar la cadena de búsqueda con la que coincide.

    Ejemplos: WHERE name LIKE 'foo %searchString% bar'
    WHERE name LIKE 'Aus%'

  • IS NULL: te permite consultar objetos con un un valor de propiedad no definido. El ejemplo clásico es la consulta de los raíz AdUnit consultando un AdUnit con un valor nulo del elemento superior.

    Ejemplo: WHERE parentId IS NULL.

  • <bind variable>. Puedes usar Value. objetos en lugar de <value> hard-coded en tu consulta de PQL. Una vinculación variable en PQL con un nombre de cadena sin espacios, a partir del con : (dos puntos).

    Ejemplo (Crea una consulta e ingresa dos variables en lugar de propiedad id y status codificadas valores):

    // Create two mapped parameters: id and status
String_ValueMapEntry[] values = new String_ValueMapEntry[2];
values[0] = new String_ValueMapEntry("id", new NumberValue(null, "123"));
values[1] = new String_ValueMapEntry("status", new TextValue(null, "APPROVED"));

// Create our statement and map our bind variables
Statement statement = new Statement();
statement.setQuery("WHERE id = :id AND status = :status LIMIT 500");
statement.setValues(values);
  • Campos DateTime: Puedes filtrar por fecha y hora por asignar un valor DateTime a una variable de vinculación o usando un cadena con formato de conformidad con ISO 8601. 
    // Create a bind variable: startDateTime
String_ValueMapEntry[] values = new String_ValueMapEntry[1];
values[0] = new String_ValueMapEntry("startDateTime", new DateTimeValue(null, dateTime));

// Create our statement and map our bind variables
Statement statement = new Statement();
statement.setQuery("WHERE endDateTime < '2019-01-01T00:00:00' AND startDateTime > :startDateTime LIMIT 500");
statement.setValues(values);

Recupera tablas de coincidencias con PQL

Las tablas de coincidencia proporcionan un mecanismo de búsqueda de los valores sin procesar que contiene archivos de transferencia de datos, lo que te permite hacer coincidir la información de publicación de anuncios (como unidad o línea de pedido) hasta los valores asignados previamente que están almacenados en la base de datos.

Si ejecuta informes a través de ReportService o con la Transferencia de datos en informes, le recomendamos que complemente los datos de estos con datos . Por ejemplo, con un informe que tiene la dimensión LINE_ITEM_ID o con un evento de transferencia de datos que tenga el campo LineItemId, puede crear una tabla de coincidencias que incluya la fecha de inicio fecha de finalización, tipo, estado y otros atributos útiles.

Existen varias formas de lograr esta funcionalidad de coincidencia:

  1. Usar las tablas de coincidencias prediseñadas que proporciona el Servicio de transferencia de datos de BigQuery. Ten en cuenta que estas tablas de coincidencias no contienen todos los campos de entidad.
  2. Un enfoque eficiente es usar cualquiera de los recursos PublisherQueryLanguageService tablas.
  3. Si no hay una tabla de BigQuery o PQL para la entidad, o la tabla faltan campos que necesitas, puedes revisar eso directamente desde el servicio de una entidad, como OrderService.

Python

Configura una consulta de informes

Para comenzar, crea un trabajo de informe y especifica los parámetros de tu informe, como los siguientes: dimensiones, columnas y períodos.

# Set the start and end dates of the report to run (past 8 days).
end_date = date.today()
start_date = end_date - timedelta(days=8)

# Create report job.
report_job = {
    'reportQuery': {
        'dimensions': ['LINE_ITEM_ID', 'LINE_ITEM_NAME'],
        'columns': ['AD_SERVER_IMPRESSIONS', 'AD_SERVER_CLICKS',
                    'AD_SERVER_CTR', 'AD_SERVER_CPM_AND_CPC_REVENUE',
                    'AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM'],
        'dateRangeType': 'CUSTOM_DATE',
        'startDate': start_date,
        'endDate': end_date
    }
}

Descargar el informe

# Initialize a DataDownloader.
report_downloader = client.GetDataDownloader(version='v202408')

try:
  # Run the report and wait for it to finish.
  report_job_id = report_downloader.WaitForReport(report_job)
except errors.AdManagerReportError as e:
  print('Failed to generate report. Error was: %s' % e)

with tempfile.NamedTemporaryFile(
    suffix='.csv.gz', mode='wb', delete=False) as report_file:
  # Download report data.
  report_downloader.DownloadReportToFile(
      report_job_id, 'CSV_DUMP', report_file)

Descarga datos de la tabla de PQL de Line_Item

Para hacer coincidir su informe con datos adicionales de la línea de pedido, puede usar el atributo Line_Item Tabla de PQL.

# Create a PQL query to fetch the line item data
line_items_pql_query = ('SELECT Id, LineItemType, Status FROM LineItem')

# Download the response from PQL select statement
line_items = report_downloader.DownloadPqlResultToList(line_items_pql_query)

Une los datos del informe con los datos de la línea de pedido

En este ejemplo, se usa pandas ya que facilita mucho el trabajo con datos tabulares. Aquí se usa para unir los datos del informe con los de PQL y crear una tabla de coincidencias.

# Use pandas to join the two csv files into a match table
report = pandas.read_csv(report_file.name)
line_items = pandas.DataFrame(data=line_items[1:], columns=line_items[0])
merged_result = pandas.merge(report, line_items,
                             left_on='Dimension.LINE_ITEM_ID', right_on='id')
merged_result.to_csv('~/complete_line_items_report.csv', index=False)
Ver en GitHub
.