En bref. Le point de terminaison de requête sur les produits d’un flux OpenAI permet d’examiner les produits correspondants avant d’enregistrer un ensemble de produits pour un groupe d’annonces.

Définition : Un annonceur peut prévisualiser le résultat d’un filtre de produits en envoyant les filtres prévus au point de terminaison de requête sur les produits d’un flux OpenAI, avant de créer ou de modifier un groupe d’annonces. La réponse contient la liste des produits correspondants et des compteurs permettant d’examiner la sélection avant d’enregistrer l’ensemble de produits.

Points clés

OpenAI documente la requête de prévisualisation sous la forme POST /v1/feeds/{feed_id}/products/query, avec un tableau filters et un paramètre facultatif limit.
Un produit doit satisfaire simultanément tous les filtres de la requête. L’exemple documenté combine un filtre sur la marque et un filtre sur le prix maximal.
Un tableau filters vide interroge le flux sans filtre supplémentaire.
L’exemple de réponse contient une liste data, ainsi que total_count et matched_count.
La référence des groupes d’annonces d’OpenAI répertorie les champs de produits pris en charge et réserve les opérateurs de comparaison à price et star_rating.

Comment prévisualiser la sélection ?

La requête utilise l’identifiant du flux associé à la campagne et les filtres prévus pour l’enregistrement. Cet exemple sélectionne les produits de la marque Acme dont le prix est inférieur ou égal à 100 unités monétaires principales :

curl -X POST "https://api.ads.openai.com/v1/feeds/fd_123/products/query" \
  -H "Authorization: Bearer ${OPENAI_ADS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {
        "field": "brand",
        "operator": "in",
        "values": ["Acme"]
      },
      {
        "field": "price",
        "operator": "lte",
        "values": ["100"]
      }
    ],
    "limit": 20
  }'

La documentation sur les flux de produits d’OpenAI indique d’interroger le flux avec les filtres prévus avant de créer ou de modifier un groupe d’annonces. Chaque produit doit satisfaire simultanément ces filtres. L’envoi de "filters": [] permet d’examiner le flux sans condition supplémentaire.

L’exemple de réponse comprend l’identifiant de l’article, la marque, le titre et le prix d’un produit renvoyé, ainsi que total_count et matched_count. L’exemple documenté renvoie un seul produit, la chaussure de trail à 89 $, tandis que la veste à 149 $ est exclue par la condition sur le prix.

Quels champs et opérateurs de filtrage sont pris en charge ?

Chaque filtre comporte un champ field, un opérateur operator et un tableau values. La référence des groupes d’annonces d’OpenAI répertorie les champs suivants pour les ensembles de produits : title, body, item_id, offer_id, price, target_url, image_url, product_category, brand, seller_name, external_seller_id, star_rating, condition et age_group. Les valeurs de comparaison numériques sont envoyées sous forme de chaînes de caractères, comme "4.5".

La référence répertorie les opérateurs in, gt, gte, lt et lte. Elle réserve gt, gte, lt et lte aux champs price ou star_rating. Elle précise également qu’un même champ ne doit pas apparaître plusieurs fois dans un ensemble de produits. Lorsqu’une intégration personnalisée prend en charge les métadonnées définies dans le flux, le guide des flux de produits documente la forme ads_metadata.<field> pour ces champs.

Comment enregistrer les filtres vérifiés ?

Après examen de la réponse, les mêmes objets de filtre sont copiés dans le champ product_set du groupe d’annonces. Le champ product_feed_id reçoit l’identifiant du flux utilisé par la campagne. Le guide des flux précise que la campagne détermine le flux utilisé et que le groupe d’annonces en hérite lorsque product_set est omis.

Une mise à jour nécessite l’envoi de l’ensemble de produits souhaité au complet, y compris les filtres à conserver. L’envoi du même identifiant de flux avec "filters": [] supprime les filtres de produits. Pour confirmer l’ensemble de produits obtenu, il faut récupérer le groupe d’annonces après la mise à jour : selon la référence des groupes d’annonces, la réponse immédiate à la mise à jour peut l’omettre.

Le résultat d’une requête constitue un aperçu de la sélection. Le guide des flux d’OpenAI précise que la seule correspondance avec un filtre ne suffit pas à établir qu’un produit recevra des impressions. La disponibilité des produits, les procédures de validation, les filtres de produits et l’éligibilité de la campagne continuent de s’appliquer après l’ingestion.

Termes associés

Questions fréquentes

Un annonceur peut-il prévisualiser le flux sans filtre ?

Oui. OpenAI documente l’utilisation d’un tableau filters vide pour examiner le flux sans filtre supplémentaire. Si le résultat sans filtre est vide, le guide invite l’annonceur à consulter l’historique des téléversements.

Un produit correspondant aux filtres reçoit-il une impression ?

L’aperçu seul ne permet de conclure à aucun résultat de diffusion. La documentation des flux précise qu’une correspondance avec un filtre ne suffit pas à établir qu’un produit recevra des impressions, et son processus de campagne prévoit de vérifier la disponibilité et les autres conditions de diffusion.

Que doit faire un annonceur si aucun produit attendu ne correspond ?

Envoyez une requête avec une liste de filtres vide, puis ajoutez les filtres prévus un par un. OpenAI documente cette démarche pour repérer la condition qui exclut les produits attendus.

Sources

Vérifiez comment une page se lit pour les moteurs de réponse. Ouvrir l’analyseur de score GEO

Comment un annonceur peut-il vérifier quels produits correspondent au filtre d’un groupe d’annonces ?