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 de domaine spécialisées 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 :

./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 de l'API (par exemple, google-ads.yaml, google_ads_php.ini ou google_ads_config.rb) se trouve 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 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 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ée : générez du code idiomatique testé à l'aide des bibliothèques clientes officielles Google Ads (Python, Java, PHP, .NET et Ruby).

    • "Affiche les campagnes ayant généré le plus de conversions au cours des 30 derniers jours."
    • "Obtiens 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.

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

  • Inspection des schémas d'objets et de 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 campagne"

  • Rapports en direct ad hoc et exportation au format CSV : demandez des données sur les performances en langage clair. 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."
    • Enregistrez les résultats au format 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é.

    • Dites à l'Assistant : Exécute le code ou Exécute le script.
    • Modification de la sécurité : pour la sécurité, les opérations de modification (création, mise à jour, suppression) sont générées pour 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 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 arborescences de partitions 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 :

      ./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 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 de comptes client. /get-cids 1234567890
/troubleshoot-conversions Exécute des diagnostics d'importation des 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 :

./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 d'assistance :

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 local de la place de marché :

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 ?