Installer et utiliser l'assistant pour les développeurs de l'API Google Ads

L'assistant pour les développeurs de l'API Google Ads apporte une expertise approfondie du domaine de l'API Google Ads directement dans votre environnement de codage IA. Utilisez des prompts en langage naturel et des commandes à barre oblique intégrées pour créer des requêtes, générer du code de bibliothèque cliente, exécuter des appels d'API en lecture seule, diffuser des rapports ad hoc et résoudre les problèmes d'intégration.

L'assistant est conçu pour les frameworks d'agents Google Antigravity et Claude Code (v4.0.0) en tant que plug-in modulaire. Il utilise des contrats AGENTS.md et CLAUDE.md, des commandes à barre oblique intégrées et des compétences de domaine spécialisées pour maintenir un contexte persistant, des limites de sécurité robustes et des pipelines de validation automatisés. Consultez Qu'est-ce que l'assistant pour les développeurs de l'API Google Ads ? pour obtenir une présentation de son architecture et de sa conception.

Prérequis

Avant de commencer, vérifiez que vous disposez des éléments suivants :

  1. Accès à l'API Google Ads :

  2. Logiciel :

Commencer

Suivez ces étapes pour cloner le dépôt, exécuter le script d'installation spécifique à la plate-forme, configurer vos identifiants et activer le plug-in.

1. Cloner le dépôt

Clonez le dépôt sur votre ordinateur local et accédez au répertoire du projet :

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. Exécuter le script d'installation

Exécutez le script d'installation pour votre plate-forme cible. Par défaut, la bibliothèque cliente Python est incluse. Vous pouvez éventuellement inclure des bibliothèques clientes supplémentaires (--php, --ruby, --java, --dotnet ou --all).

Antigravity

Linux / macOS :

./install.sh agy
# Or include additional client libraries:
./install.sh agy --java --dotnet

Windows (PowerShell) :

.\install.ps1 -Type agy
# Or include additional client libraries:
.\install.ps1 -Type agy -Java -Dotnet

Claude Code

Linux / macOS :

./install.sh claude
# Or include additional client libraries:
./install.sh claude --php --dotnet

Windows (PowerShell) :

.\install.ps1 -Type claude
# Or include additional client libraries:
.\install.ps1 -Type claude -Php -Dotnet

3. Configurer les identifiants

Assurez-vous que votre fichier de configuration d'API (par exemple, google-ads.yaml, google_ads_php.ini ou google_ads_config.rb) est placé dans votre répertoire $HOME.

(Facultatif) Pour configurer un numéro client par défaut, saisissez-le directement dans config/customer_id.txt (par exemple, 1234567890). Vous pouvez également inspecter ou épingler votre version d'API active dans config/api_version.txt.

4. Activer le plug-in

  • Antigravity : redémarrez votre session hôte Antigravity / agy pour charger le plug-in.
  • Claude Code : dans une session Claude Code active, exécutez /reload-plugins ou redémarrez claude.

5. Interagir avec l'Assistant

Vous pouvez interagir avec l'Assistant à l'aide de requêtes en langage naturel ou de commandes à barre oblique dédiées directement dans votre terminal.

Principales fonctionnalités

  • Questions/réponses en langage naturel et conseils conceptuels : posez des questions sur les fonctionnalités de l'API Google Ads, les règles d'architecture, les bonnes pratiques ou des ressources spécifiques. L'assistant fonde ses réponses sur les définitions officielles de l'API plutôt que de s'appuyer uniquement sur l'entraînement général du LLM.

    • "Quels sont les types de campagnes disponibles ?"
    • "Comment filtrer par date dans GAQL ?"
    • "Explique la différence entre click_view et impression_view."
    • "Qu'est-ce qu'un ensemble partagé et comment l'utiliser ?"
    • Commandes à barre oblique Claude Code : /explain, /step-by-step, /assistant-tutorial

  • Génération de code de bibliothèque cliente ancrée : générez du code idiomatique testé à l'aide des bibliothèques clientes Google Ads officielles (Python, Java, PHP, .NET et Ruby).

    • "Affiche les campagnes ayant enregistré le plus de conversions au cours des 30 derniers jours."
    • "Obtenir tous les noms de groupes d'annonces activés pour le client 123-456-7890."
    • "Écris du code pour créer une campagne Performance Max." Le code généré est enregistré dans le répertoire saved/code/.

  • Validation programmatique des requêtes GAQL : effectuez automatiquement un dry run et validez les requêtes complexes par rapport aux métadonnées de l'API, à la compatibilité des champs, aux règles de zéro impression et à la segmentation par date avant l'exécution.

    • Claude Code : /validate-gaql
    • Langage naturel : validate: SELECT campaign.id FROM campaign

  • Inspection des schémas d'objets et Protobuf : inspectez de manière dynamique les structures de ressources, les champs imbriqués, les types de données et les valeurs d'énumération pour toute version d'API active, sans surcharge de métadonnées distantes.

    • Claude Code : /inspect-object <resource_or_enum>
    • Langage naturel : "Inspecter la ressource de campagne"

  • Rapports en direct ad hoc et exportation au format CSV : demandez des données sur les performances en anglais simple. L'Assistant crée, valide et exécute des requêtes GAQL directement sur votre compte, en diffusant des tableaux formatés en direct dans le terminal.

    • "Affiche les cinq mots clés ayant généré le plus de coûts le mois dernier pour le client 123-456-7890."
    • "Enregistre les résultats dans un fichier CSV." (exportation vers saved/csv/).

  • Exécution directe de l'API et sécurité des mutations : exécutez les scripts en lecture seule générés directement dans un environnement virtuel géré.

    • Dites à l'Assistant : "Exécute le code" ou "Exécute le script".
    • Sécurité des mutations : pour des raisons de sécurité, les opérations de mutation (création, mise à jour, suppression) sont générées dans saved/code/, mais ne sont jamais exécutées directement par l'assistant. Examinez-les et exécutez-les manuellement en dehors de l'assistant.

  • Diagnostics avancés et dépannage des conversions : examinez les échecs d'importation des conversions hors connexion, prévalidez les fichiers d'importation et générez des rapports de diagnostic détaillés.

    • Claude Code : /troubleshoot-conversions
    • Langage naturel : "Résous les problèmes de conversion pour le client 123-456-7890." (Rapports enregistrés dans saved/data/).

  • Mappage de la hiérarchie des comptes administrateur : récupérez les numéros client des sous-comptes et mappez les hiérarchies de comptes sous un compte administrateur.

    • Claude Code : /get-cids <manager_cid>
    • Langage naturel : "Get all client customer IDs under manager 123-456-7890"

  • Filtres et exclusions de fiches Performance Max : générez des arborescences de partitions de produits et des exclusions d'URL de pages Web pour les groupes de composants.

    • Claude Code : /pmax-filter
    • Langage naturel : "Crée des filtres d'exclusion de pages Web pour ma campagne PMax"

  • Contexte de codebase supplémentaire : enregistrez votre logique d'application et votre architecture personnalisée dans le raisonnement de l'Assistant.

    • Linux / macOS :

      ./update.sh agy --context_dir /path/to/your/codebase
# Or for Claude Code:
./update.sh claude --context_dir /path/to/your/codebase

    • Windows (PowerShell) :

      .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Documentation de référence sur les commandes à barre oblique Claude Code

Lorsque vous utilisez Claude Code, les commandes à barre oblique intégrées suivantes sont disponibles. Dans Google Antigravity, appelez ces mêmes fonctionnalités à l'aide de requêtes en langage naturel ou de noms d'outils de compétences tels que validate_gaql et inspect_object, comme décrit dans Fonctionnalités clés :

Commande à barre oblique Objectif Exemple
/validate-gaql Valide la syntaxe, la compatibilité et les règles GAQL. /validate-gaql
/inspect-object Inspecte les champs, les types et les énumérations Protobuf. /inspect-object Campaign
/get-cids Résout les hiérarchies de comptes administrateur et les numéros client. /get-cids 1234567890
/troubleshoot-conversions Exécute les diagnostics d'importation des conversions hors connexion. /troubleshoot-conversions
/pmax-filter Génère des filtres et des exclusions de fiches PMax. /pmax-filter
/explain Fournit une explication structurée en quatre parties. /explain shared set
/step-by-step Formule un plan d'exécution de tâches en plusieurs phases. /step-by-step upload conversions
/assistant-tutorial Exécute un tutoriel interactif en 11 étapes. /assistant-tutorial

Maintenance et mises à jour

Pour mettre à jour le dépôt, l'installation du plug-in et les bibliothèques clientes :

Antigravity

Linux / macOS :

./update.sh agy          # Update Antigravity plugin
./update.sh agy --all    # Include all client libraries

Windows (PowerShell) :

.\update.ps1 -Type agy
.\update.ps1 -Type agy -All

Claude Code

Linux / macOS :

./update.sh claude       # Update Claude Code plugin
./update.sh claude --all # Include all client libraries

Windows (PowerShell) :

.\update.ps1 -Type claude
.\update.ps1 -Type claude -All

Désinstallation

Pour désinstaller le plug-in de l'assistant :

Antigravity

Linux / macOS :

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell) :

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Redémarrez ensuite votre session hôte Antigravity.

Claude Code

Dans une session Claude Code active :

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Ou depuis votre terminal :

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

(Facultatif) Supprimez le registre Marketplace local :

claude plugin marketplace remove google-ads-assistant-local

Communauté et support

Consignes de contribution

Les contributions sont les bienvenues. Pour obtenir des instructions, consultez le fichier CONTRIBUTING.md dans le dépôt GitHub.

Étapes suivantes

Précédent
Qu'est-ce que l'assistant pour les développeurs de l'API Google Ads ?