Cette page a été traduite par l'API Cloud Translation.

Guide du développeur PQL (Publisher Query Language)

Syntaxe et utilisation de PQL

PQL est un langage de type SQL permettant d'interroger des objets. La syntaxe PQL est semblable à celle de SQL, avec quelques différences décrites ici. Cette section décrit la syntaxe PQL et explique comment l'utiliser pour filtrer différents types d'objets.

La syntaxe PQL peut être résumée comme suit:

[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>

Remarques

Les mots clés PQL ne sont pas sensibles à la casse.
Les chaînes sont automatiquement échappées lorsqu'elles sont utilisées dans des paramètres de liaison. Sinon :
- Pour une chaîne entre guillemets simples (apostrophes), échappez toute apostrophe supplémentaire en l'écrivant sous la forme d'une paire de guillemets simples.
  Exemple : "WHERE name = 'Company''s name'"

Mots clés (non sensibles à la casse)

WHERE : exprime un ensemble de zéro ou plusieurs conditions, éventuellement associées à l'aide de phrases ET ou OU. Vous pouvez regrouper les expressions ET ou OU avec des parenthèses. L'exécution de la requête "" (chaîne vide) renvoie tout.
Exemples WHERE width = 728
WHERE width = 728 AND height = 90
WHERE (width = 728 AND height = 90) OR id IN (5008, 8745, 3487)
OR : joint plusieurs conditions, dont une seule doit être vraie. Si vous souhaitez vérifier plusieurs valeurs pour une seule propriété, envisagez d'utiliser une clause IN.
Exemple : WHERE width = 728 OR height = 90
AND : joint plusieurs conditions qui doivent toutes être remplies à l'aide de la clause AND.
Exemple : WHERE type = 'AGENCY' AND name IN ('CompanyNameA', 'CompanyNameB')
ORDER BY : trie les résultats renvoyés par ordre croissant (ASC où "A" apparaît en premier) ou décroissant (DESC où "A" est en dernier). Si le sens n'est pas spécifié, la valeur par défaut est ASC. Si cette clause n'est pas incluse, la valeur par défaut est ASC dans le premier champ.
Exemple : WHERE id IN (5008, 8745, 3487) ORDER BY id
LIMIT : nombre de résultats à renvoyer. Le LIMIT peut également inclure un <offset>, qui correspond au nombre de lignes à partir du début pour décaler votre ensemble de résultats.
Exemples (les deux exemples renvoient le même ensemble de résultats):
WHERE type = 'AGENCY' LIMIT 50 OFFSET 50
WHERE type = 'AGENCY' LIMIT 50,50
OFFSET : décalage dans l'ensemble de résultats pour commencer à renvoyer des valeurs. Utilisez-le pour parcourir les résultats.
Exemple (renvoie les résultats 51 à 100):
WHERE type = 'AGENCY' LIMIT 50 OFFSET 50.
<property> : l'une des propriétés exposées par l'objet. Chaque objet expose des propriétés différentes que vous pouvez filtrer à l'aide de PQL. Vous ne pouvez généralement pas filtrer toutes les propriétés compatibles avec un objet. Consultez la liste ci-dessous pour savoir quelles propriétés sont compatibles avec les requêtes PQL. Par exemple, les propriétés de création que vous pouvez filtrer incluent id, name, width et height.
<value> : les valeurs de chaîne doivent être placées entre guillemets simples ('). Les valeurs numériques peuvent être placées entre guillemets ou sans guillemets. Les caractères génériques ne sont pas acceptés.
IN : compare la valeur d'une propriété à chaque élément d'une liste. Si l'un d'eux correspond, il s'agit d'une correspondance positive. L'opérateur IN équivaut à plusieurs requêtes = (une pour chaque valeur) auxquelles l'opérateur OR est appliqué. Les valeurs sont spécifiées sous la forme d'une liste de valeurs séparées par une virgule et entre parenthèses: (a, b, c). Toutes les valeurs de la liste sont évaluées.
Exemple : WHERE name IN ('CompanyNameA', 'CompanyNameB')
NOT IN : compare la valeur d'une propriété à chaque élément d'une liste. Si aucune correspondance n'est trouvée, il s'agit d'une correspondance positive. L'opérateur NOT IN équivaut à plusieurs requêtes != (une pour chaque valeur) auxquelles l'opérateur OR est appliqué. Les valeurs sont spécifiées sous la forme d'une liste de valeurs séparées par une virgule et entre parenthèses: (a, b, c). Toutes les valeurs de la liste sont évaluées.
Exemple : WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')
LIKE : permet d'interroger des objets en utilisant la mise en correspondance de chaînes génériques. Le signe de pourcentage (%) représente zéro, un ou plusieurs caractères. Utilisez une paire pour délimiter la chaîne de recherche mise en correspondance.
Exemples:WHERE name LIKE 'foo %searchString% bar'
WHERE name LIKE 'Aus%'
IS NULL : vous permet d'interroger les objets dont la valeur de propriété n'est pas définie. L'exemple classique consiste à interroger la racine AdUnit en interrogeant un AdUnit avec un ID parent nul.
Exemple : WHERE parentId IS NULL.

<bind variable> : vous pouvez utiliser des objets Value à la place des valeurs <value> codées en dur dans votre requête PQL. Une variable de liaison est appelée dans PQL à l'aide d'un nom de chaîne sans espaces, commençant par un deux-points (:).

Exemple (crée une requête et saisit deux variables à la place des valeurs de propriété id et status codées en dur):

// 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);

Champs DateTime : vous pouvez filtrer par date et heure en attribuant une valeur DateTime à une variable de liaison, ou en utilisant une chaîne formatée conformément à la norme 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);

Extraire les tables des correspondances avec PQL

Les tables de correspondance fournissent un mécanisme de recherche pour les valeurs brutes contenues dans les fichiers de transfert de données. Vous pouvez ainsi établir des correspondances entre les informations sur la diffusion des annonces (telles que les blocs d'annonces ou les éléments de campagne) et les valeurs préattribuées stockées dans la base de données.

Si vous générez des rapports via ReportService ou avec des rapports sur les transferts de données, vous pouvez ajouter des champs à vos données de rapport. Par exemple, avec un rapport avec la dimension LINE_ITEM_ID ou un événement de transfert de données associé au champ LineItemId, vous pouvez créer une table des correspondances incluant la date de début, la date de fin, le type, l'état et d'autres attributs utiles pour chaque élément de campagne.

Il existe plusieurs façons de mettre en œuvre cette fonctionnalité de mise en correspondance:

Utilisez les tables de correspondance prédéfinies fournies par le service de transfert de données BigQuery. Notez que ces tables des correspondances ne contiennent pas tous les champs d'entité.
Une approche efficace consiste à utiliser l'une des tables PublisherQueryLanguageService disponibles.
S'il n'existe pas de table BigQuery ou PQL pour l'entité, ou s'il manque des champs dont vous avez besoin dans la table, vous pouvez passer directement par le service de cette entité, par exemple OrderService.

Python

Configurer une requête de rapport

Commencez par créer une tâche de rapport en spécifiant les paramètres de votre rapport tels que les dimensions, les colonnes et la plage de dates.

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

Télécharger le rapport

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

Télécharger les données de la table PQL de l'élément de campagne

Pour faire correspondre votre rapport à des données supplémentaires sur les éléments de campagne, vous pouvez utiliser la table 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)

Associer les données du rapport aux données des éléments de campagne

Cet exemple utilise la bibliothèque pandas, car elle facilite grandement l'utilisation des données tabulaires. Ici, il permet de joindre les données du rapport aux données PQL afin de créer une table des correspondances.

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

Afficher sur GitHub