Bonnes pratiques

Cette page présente diverses bonnes pratiques à prendre en compte lors du développement d'applications avec l'API Google Ad Manager.

Réutiliser les clients de service/bouchons au cours d'une exécution

La création d'un nouveau client ou d'un bouchon de service entraîne un coût marginal associé à l'extraction du WSDL et à l'allocation des ressources. Si possible, créez le client de service/bouchon une fois au début d'une exécution et mettez-le à la disposition des classes et des fonctions selon les besoins.

Utiliser la pagination lors de la récupération d'objets

Tous les services sont compatibles avec la méthode get*ByStatement(), qui permet de filtrer les résultats à l'aide de la syntaxe PQL. Les clauses LIMIT et OFFSET peuvent être utilisées pour diviser des ensembles de résultats volumineux en pages, ce qui permet d'éviter les délais d'inactivité et de maintenir des tailles de page de réponse raisonnables. La taille de page suggérée est comprise entre 200 et 500, en fonction de la complexité de vos objets.

Requêtes de mise à jour groupée

Lorsque vous modifiez plusieurs objets du même type, vous pouvez obtenir de meilleures performances en envoyant tous les objets dans la même requête update*(). Chaque requête entraîne une surcharge marginale sur le client et le serveur, et le traitement par lot peut être un moyen efficace de réduire le nombre de requêtes. Par exemple, utilisez updateOrders pour mettre à jour un lot de commandes plutôt qu'une seule commande dans chaque appel.

Utiliser des paramètres de liaison dans PQL

Les paramètres de liaison sont un moyen de placer des variables dans une instruction de requête PQL. PQL fait référence à une variable de liaison par un nom sans espaces commençant par le signe deux-points (par exemple, :name. Vous trouverez un exemple de code sur la page Syntaxe PQL.

Nous vous recommandons d'utiliser des variables de liaison, car elles améliorent la lisibilité du code en supprimant la nécessité de concaténer des chaînes et des variables dans une instruction de requête. Ils facilitent également la réutilisation des instructions PQL, car de nouvelles requêtes peuvent être créées en remplaçant les valeurs des paramètres de liaison.

Accorder des droits aux utilisateurs avec parcimonie

Lorsque vous utilisez UserService pour créer ou mettre à jour des rôles utilisateur, veillez à ne pas accorder aux utilisateurs des droits dont ils n'ont pas besoin. Il est possible d'accéder à de nombreuses fonctionnalités de l'API avec une combinaison de rôles plutôt que d'attribuer un rôle d'administrateur à l'utilisateur. Veuillez consulter la documentation sur les autorisations pour déterminer les rôles à attribuer à un utilisateur. De plus, en tant que développeur d'applications tierces, veillez à déterminer le niveau d'accès dont votre application a besoin lorsque vous demandez à un réseau de créer un utilisateur pour vous. Un rôle disposant de moins de droits que celui d'administrateur peut suffire.

Respecter les limites de quota

L'API Ad Manager applique plusieurs limites de quota pour plus de fiabilité. Il est important que vos applications restent en dessous de ces limites et que vous sachiez comment répondre aux erreurs de quota que l'API peut renvoyer.

Quota d'API

Le premier quota appliqué aux requêtes API est un quota au niveau du réseau. Pour les comptes Ad Manager 360, la limite est de 8 requêtes par seconde. Pour les comptes Ad Manager, la limite est de 2 requêtes par seconde. Le dépassement de cette limite génère une erreur QuotaError.EXCEEDED_QUOTA. Toutes les requêtes API effectuées sur votre réseau s'appliquent à ce quota, y compris les applications tierces que vous ou une autre personne de votre entreprise avez autorisées à accéder à l'API sur votre réseau.

Quotas spécifiques au système

Le quota d'API à lui seul ne suffit pas à protéger de manière adéquate certains systèmes gourmands en ressources dans Ad Manager. Les systèmes de création de rapports et de prévision définissent leurs propres quotas, ce qui peut entraîner des erreurs d'API : QuotaError.REPORT_JOB_LIMIT et ForecastError.EXCEEDED_QUOTA, respectivement.

Gérer les erreurs de quota

Si votre application rencontre l'une des erreurs de quota ci-dessus, appliquez une stratégie pour relancer la requête API. Nous vous recommandons d'attendre au moins cinq secondes d'abord. Si l'erreur persiste, utilisez un intervalle exponentiel entre les tentatives pour augmenter le délai entre les tentatives. Si les nouvelles tentatives n'aboutissent pas, effectuez un audit de vos applications d'API pour voir si des utilisateurs de votre réseau drainent votre quota.