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 programmation d'IA. Utilisez des requêtes en langage naturel et des commandes slash 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 slash 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 :

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

Vous pouvez également inclure des bibliothèques clientes supplémentaires :

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

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

Vous pouvez également inclure des bibliothèques clientes supplémentaires :

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

Claude Code

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

Vous pouvez également inclure des bibliothèques clientes supplémentaires :

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

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

Vous pouvez également inclure 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 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 active de l'API 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 slash dédiées directement dans votre terminal.

Principales fonctionnalités

  • Questions/réponses en langage naturel : posez des questions sur les fonctionnalités de l'API Google Ads, les bonnes pratiques ou des ressources spécifiques.

  • 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 ancre ses réponses dans les définitions officielles des API au lieu 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 ?"
    • "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é : 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 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 sur les impressions nulles et à la segmentation par date avant l'exécution.

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

  • Inspection des schémas d'objet 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 n'importe quelle version active de l'API, sans surcharge de métadonnées à distance.

    • Code Claude : /inspect-object <resource_or_enum>
    • Langage naturel : "Inspecter la ressource de la 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 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 pour le mois dernier pour le client 123-456-7890."
    • "Enregistre les résultats dans un fichier CSV." (Exportations 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é.

    • Il vous suffit de dire à 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 sur 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 conversions : examinez les échecs d'importation des conversions hors connexion, prévalidez les fichiers à importer et générez des rapports de diagnostic détaillés.

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

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

    • Code Claude : /get-cids <manager_cid>
    • Langage naturel : "Obtiens tous les numéros client sous le compte administrateur 123-456-7890"

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

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

  • Contexte supplémentaire de la codebase : 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 slash de Claude Code

Lorsque vous utilisez Claude Code, les commandes slash 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étence 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 CM et les numéros client. /get-cids 1234567890
/troubleshoot-conversions Exécute des diagnostics d'importation de conversions hors connexion. /troubleshoot-conversions
/pmax-filter Génère des filtres et des exclusions pour les 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 des 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 : 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 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 Marketplace local : bash claude plugin marketplace remove google-ads-assistant-local

Communauté et support

Consignes de contribution

Les 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 ?