Se usó la API de Cloud Translation para traducir esta página.

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 a la de SQL, con algunas diferencias que se describen aquí. En esta sección, se 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 tienen un escape automático cuando se usan en parámetros de vinculación. De lo contrario, haz lo siguiente:
- Para una string entre comillas simples (apóstrofos), escapa cualquier apóstrofo adicional escribiéndola como un par de comillas simples.
  Ejemplo: "WHERE name = 'Company''s name'".

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

WHERE: Expresa un conjunto de cero o más condiciones, unidas opcionalmente mediante frases O o Y. Puedes agrupar las frases AND u OR con paréntesis. Cuando se ejecuta la consulta "" (string vacía), se 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. Solo una de las cuales debe ser verdadera. Si quieres verificar cualquiera de los diversos valores de una sola propiedad, considera usar una cláusula IN.
Ejemplo: WHERE width = 728 OR height = 90.
AND: Une varias condiciones que se deben cumplir mediante la cláusula AND.
Ejemplo: WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB').
ORDER BY: Ordena los resultados que se muestran de forma ascendente (ASC, donde “A” es primero) o descendente (DESC donde “A” es la última). Si no se especifica la dirección, el valor predeterminado es ASC. Si no se incluye esta cláusula, el valor predeterminado será 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 la cantidad de filas desde el principio para compensar tu conjunto de resultados.
Ejemplos (ambos muestran el mismo conjunto de resultados):
WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
WHERE type = 'AGENCY' LIMIT 50,50
OFFSET: Es el desplazamiento del conjunto de resultados para comenzar a mostrar valores. Úsalo para desplazarte por los resultados.
Ejemplo (muestra los resultados 51 a 100):
WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.
<property>: Es una de las propiedades que expone el objeto. Cada objeto expone diferentes propiedades que puedes filtrar mediante PQL. Por lo general, no puedes filtrar todas las propiedades compatibles con un objeto. Por lo tanto, revisa la lista a continuación 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 entre comillas simples ('). Los valores numéricos pueden estar entre comillas o no. No se admiten comodines.
IN: Compara el valor de una propiedad con cada elemento de una lista. Si alguno coincide, es una coincidencia positiva. El operador IN es equivalente a muchas consultas =, una para cada valor, que se unen mediante OR. Los valores se especifican como una lista de valores separados por comas, encerrado entre paréntesis: (a, b, c). Se evalúan todos los valores de la lista.
Ejemplo: WHERE name IN ('CompanyNameA', 'CompanyNameB').
NOT IN: Compara el valor de una propiedad con cada elemento de una lista. Si no hay coincidencia, es una coincidencia positiva. El operador NOT IN es equivalente a muchas consultas !=, una para cada valor, que se unen mediante OR. Los valores se especifican como una lista de valores separados por comas, encerrado entre paréntesis: (a, b, c). Se evalúan todos los valores de la lista.
Ejemplo: WHERE NOT name IN ('CompanyNameA', 'CompanyNameB').
LIKE: Te permite buscar objetos mediante la coincidencia de strings de comodín. El signo de porcentaje (%) representa cero, uno o varios caracteres. Usa un par para encerrar la string de búsqueda con la que se encuentra la coincidencia.
Ejemplos: WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'
IS NULL: Te permite buscar objetos con un valor de propiedad no definido. El ejemplo clásico consiste en consultar la AdUnit raíz mediante la consulta de un AdUnit con un ID superior nulo.
Ejemplo: WHERE parentId IS NULL.

<bind variable>: Puedes usar objetos Value en lugar de valores <value> codificados en tu consulta de PQL. Se hace referencia a una variable de vinculación en PQL con un nombre de string sin espacios, que comienza con : (dos puntos).

Ejemplo (crea una consulta y, luego, ingresa dos variables en lugar de los valores de las propiedades id y status hard-coded):

// 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 asignando un valor DateTime a una variable de vinculación o usando una string con formato 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 coincidencias proporcionan un mecanismo de búsqueda de los valores sin procesar contenidos en los archivos de transferencia de datos, lo que te permite hacer coincidir la información de publicación de anuncios (como la unidad de anuncios o la línea de pedido) con los valores asignados previamente que están almacenados en la base de datos.

Si ejecutas informes a través de ReportService o con los informes de Transferencia de datos, te recomendamos que complementes los datos de tus informes con campos adicionales. Por ejemplo, con un informe que tiene la dimensión LINE_ITEM_ID o un evento de transferencia de datos que tenga el campo LineItemId, puedes crear una tabla de coincidencias que incluya la fecha de inicio, la fecha de finalización, el tipo, el estado y otros atributos útiles de cada línea de pedido.

Existen varias formas de lograr esta funcionalidad de concordancia:

Usa 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.
Un enfoque eficiente es usar cualquiera de las tablas de PublisherQueryLanguageService disponibles.
Si no hay una tabla de BigQuery o PQL para la entidad, o si a la tabla le faltan campos que necesitas, puedes pasar por el servicio de esa entidad directamente, como OrderService.

Python

Configura una consulta de informes

Para comenzar, crea un trabajo de informe y especifica los parámetros del informe, como dimensiones, columnas y período.

# 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 informe

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

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 Line_Item

Para hacer coincidir tu informe con datos de líneas de pedido adicionales, puedes usar la tabla de PQL Line_Item.

# 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 las líneas de pedido

En este ejemplo, se usa la biblioteca de Pandas, ya que facilita mucho el trabajo con datos tabulares. Aquí, se usa para unir los datos del informe con los datos de PQL para 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