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 son utilisation pour filtrer divers 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>

Important: Le service ReportService n'accepte qu'un sous-ensemble de la syntaxe PQL. Voir la classe ReportQuery pour en savoir plus.

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: <ph type="x-smartling-placeholder">
  </ph>

  • Pour une chaîne placée entre guillemets simples (apostrophes), échappez tout une 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 jointes à l'aide d'expressions AND ou OR. Vous pouvez regrouper des expressions avec les opérateurs AND ou OR avec des parenthèses. Exécuter la requête "" (vide) chaîne) 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 doit être vraie. Si vous souhaitez vérifier l'une des valeurs , envisagez d'utiliser une clause IN.

  Exemple : WHERE width = 728 OR height = 90

• AND : joint plusieurs conditions qui doivent toutes être satisfait à l'aide de la clause AND.

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

• ORDER BY : trie les résultats renvoyés soit croissant (ASC où "A" est affiché en premier) ou décroissant (DESC, où "A" est le dernier). Si la direction 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. La LIMIT peut également inclure un <offset>, qui est le 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 renvoyant des valeurs. Utilisez-le pour parcourir les pages de 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 . Chaque objet présente différentes propriétés que vous pouvez utiliser comme critères de filtrage, à l'aide de PQL, vous ne pouvez généralement pas filtrer sur toutes les propriétés prises en charge par un Consultez la liste ci-dessous pour connaître les propriétés compatibles avec les requêtes PQL. Par exemple, vous pouvez filtrer les propriétés de création suivantes : id, name, width et height.
• <value> : les valeurs de chaîne doivent être placées entre guillemets guillemet simple ('). Les valeurs numériques peuvent être entre guillemets ou non. Caractères génériques ne sont pas acceptés.
• IN : compare la valeur d'une propriété à chaque élément d'une list si l'un d'entre eux correspond, il s'agit d'une correspondance positive. IN équivaut à plusieurs requêtes =, une pour chaque valeur, qui sont liés par l'opérateur OR. Les valeurs sont spécifiées sous la forme d'une liste de entre parenthèses: (a, b, c). Toutes les valeurs de la liste évalué.

  Exemple : WHERE name IN ('CompanyNameA', 'CompanyNameB')

• NOT IN : compare la valeur d'une propriété à chaque élément dans une liste ; si aucune correspondance n'est établie, il s'agit d'une correspondance positive. NOT IN équivaut à plusieurs requêtes !=, une pour chaque valeur, qui sont liés par l'opérateur OR. Les valeurs sont spécifiées sous la forme d'une liste de entre parenthèses: (a, b, c). Toutes les valeurs de la liste évalué.

  Exemple : WHERE NOT name IN ('CompanyNameA', 'CompanyNameB')

• LIKE : permet d'interroger des objets à l'aide de caractères génériques. la mise en correspondance des chaînes. Le signe de pourcentage (%) représente zéro, un ou plusieurs caractères. Utilisez une paire pour délimiter la chaîne de recherche à laquelle correspond la correspondance.

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

• IS NULL : permet d'interroger des objets avec une non définie. L'exemple classique est d'interroger racine AdUnit en interrogeant AdUnit avec une valeur nulle ID parent.

  Exemple : WHERE parentId IS NULL.

• <bind variable> - Vous pouvez utiliser Value à la place de <value> codées en dur dans votre requête PQL. Une liaison est appelée dans PQL par un nom de chaîne sans espaces, par un ":" (deux-points).

  Exemple (crée une requête et saisit deux variables à la place de propriété id et status codée 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 par en attribuant une valeur DateTime à une variable de liaison, ou en utilisant un 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 des tableaux de correspondance avec PQL

Les tableaux de correspondance fournissent un mécanisme de recherche pour les valeurs brutes contenues dans fichiers de transfert de données, qui vous permettent d'établir des correspondances entre les informations de diffusion des annonces (telles que unité ou article) à des valeurs pré-attribuées stockées dans la base de données.

Si vous générez des rapports via le service ReportService ou avec Data Transfer , vous pouvez les compléter avec des données . Par exemple, pour un rapport comportant la dimension LINE_ITEM_ID, ou avec un événement de transfert de données comportant le champ LineItemId, vous pouvez créer un tableau des correspondances qui inclut la date de début de chaque élément de campagne, la date de fin, le type, l'état et d'autres attributs utiles.

Il existe plusieurs façons d'obtenir cette fonctionnalité de mise en correspondance:

1. Utilisez les tableaux de correspondance prédéfinis fournis par <ph type="x-smartling-placeholder"></ph> Service de transfert de données BigQuery Notez que ces tables des correspondances ne contiennent pas tous les champs d'entité.
2. Une approche efficace consiste à utiliser n'importe quel PublisherQueryLanguageServiceService de données.
3. S'il n'y a pas de table BigQuery ou PQL pour l'entité, ou s'il manque les champs dont vous avez besoin dans la table, vous pouvez passer par cette directement au service de l'entité, par exemple OrderService.

Python

Configurer une requête de rapport

Commencez par créer une tâche de rapport, en spécifiant ses paramètres de rapport tels que 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='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)

Télécharger les données depuis la table PQL Line_Item

Pour mettre en correspondance votre rapport avec d'autres données sur les éléments de campagne, vous pouvez utiliser l'élément Line_Item table 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)
    

Associer les données de rapport aux données d'élément de campagne

Cet exemple utilise l'API pandas car il facilite grandement le travail avec des données tabulaires. Ici, il est utilisé pour associer 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