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 intègre une expertise approfondie du domaine de l'API Google Ads directement dans votre environnement de codage d'IA. Utilisez des invites 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'agent Google Antigravity et Claude Code (v4.0.0) en tant que plug-in modulaire. Il utilise les contrats AGENTS.md et CLAUDE.md, les commandes à barre oblique intégrées et des compétences spécialisées dans le domaine pour maintenir un contexte persistant, des limites de sécurité robustes et des pipelines de validation automatisés.

Prérequis

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

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

  2. Logiciel :

Premiers pas

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 machine locale 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 : ```bash ./install.sh agy

Ou incluez des bibliothèques clientes supplémentaires :

./install.sh agy --java --dotnet ```

Windows (PowerShell) : ```powershell .\install.ps1 -Type agy

Ou incluez des bibliothèques clientes supplémentaires :

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

Linux / macOS : ```bash ./install.sh claude

Ou incluez des bibliothèques clientes supplémentaires :

./install.sh claude --php --dotnet ```

Windows (PowerShell) : ```powershell .\install.ps1 -Type claude

Ou incluez des bibliothèques clientes supplémentaires :

.\install.ps1 -Type claude -Php -Dotnet ```

3. Configurer les identifiants

Assurez-vous que votre fichier de configuration de l'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 ID client par défaut, saisissez votre numéro d'ID client 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 d'invites 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 ou des ressources spécifiques. L'Assistant base 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 des LLM.

    • "Quels sont les types de campagnes disponibles ?"
    • "Comment filtrer par date dans GAQL ?"
    • "Expliquez 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 basé sur des données : générez du code testé et idiomatique à l'aide des bibliothèques clientes Google Ads officielles (Python, Java, PHP, .NET et Ruby).

    • "Affiche-moi les campagnes qui ont généré le plus de conversions au cours des 30 derniers jours."
    • "Récupère 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 : exécutez et validez automatiquement des requêtes complexes par rapport aux métadonnées de l'API, à la compatibilité des champs, aux règles d'absence d'impressions 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 dynamiquement les structures de ressources, les champs imbriqués, les types de données et les valeurs d'énumération pour n'importe quelle version d'API active sans surcharge de métadonnées à distance.

    • 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 langage simple. L'Assistant crée, valide et exécute des requêtes GAQL directement dans votre compte, en diffusant des tableaux mis en forme en direct dans le terminal.

    • "Affiche les cinq principaux mots clés par coût 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 simplement à 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 résolution des problèmes de conversion : examinez les échecs d'importation de 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ésoudre les problèmes de conversion pour le client 123-456-7890." (Rapports enregistrés dans saved/data/).

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

    • Claude Code: /get-cids <manager_cid>
    • Langage naturel "Récupérer tous les ID client sous l'administrateur 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éer des filtres d'exclusion de pages Web pour ma campagne Performance Max"

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

    • Linux / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): 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 d'invites en langage naturel ou de noms d'outils de compétences tels que validate_gaql et inspect_object, comme décrit dans la section Principales fonctionnalité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 CM et les CIDs client. /get-cids 1234567890
/troubleshoot-conversions Exécute les diagnostics d'importation de conversions hors connexion. /troubleshoot-conversions
/pmax-filter Génère des filtres et des exclusions de fiches Performance Max. /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 une procédure pas à pas interactive 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: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

Linux / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

Désinstallation

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

Antigravity

Linux / macOS: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): 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 : none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Ou depuis votre terminal : bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Facultatif) Supprimez le registre de la place de marché locale : bash claude plugin marketplace remove google-ads-assistant-local

Communauté et support

Consignes de contribution

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

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