Les services avancés de Google Apps Script vous permettent de vous connecter à certaines API Google publiques avec moins de configuration que leurs interfaces HTTP. Les services avancés sont des wrappers de bas niveau pour ces API Google. Ils fonctionnent de la même manière que les services intégrés d'Apps Script. Par exemple, ils proposent la saisie semi-automatique et Apps Script gère automatiquement le flux d'autorisation. Activez un service avancé avant de l'utiliser dans un script.
Activer les services avancés
Pour utiliser un service Google avancé, suivez ces instructions :
Étape 1 : Activez le service avancé
Activez un service avancé à l'aide de l'éditeur Apps Script ou en modifiant le fichier manifeste.
Méthode A : Utiliser l'éditeur
- Ouvrez le projet Apps Script.
- À gauche, cliquez sur Montage .
- Sur la gauche, à côté de Services, cliquez sur Ajouter un service .
- Sélectionnez un service Google avancé, puis cliquez sur Ajouter.
Méthode B : Utiliser le fichier manifeste
Activez les services avancés en modifiant le fichier manifeste. Par exemple, pour activer le service Google Drive avancé, ajoutez le champ enabledAdvancedServices à l'objet dependencies :
{
"timeZone": "America/Denver",
"dependencies": {
"enabledAdvancedServices": [
{
"userSymbol": "Drive",
"version": "v3",
"serviceId": "drive"
}
]
},
"exceptionLogging": "STACKDRIVER",
"runtimeVersion": "V8"
}
Une fois que vous avez activé un service avancé, il est disponible dans la saisie semi-automatique.
Étape 2 : Activez l'API Google Cloud (projets Google Cloud standards uniquement)
Si vous utilisez un projet Google Cloud par défaut (créé automatiquement par Apps Script), ignorez cette étape. L'API est activée automatiquement lorsque vous ajoutez le service à l'étape 1.
Si vous utilisez un projet Google Cloud standard, activez manuellement l'API correspondant au service avancé. Pour activer l'API manuellement :
Ouvrez le projet Cloud associé à votre script dans la **console Google Cloud**.
En haut de la console, cliquez dans la barre de recherche et saisissez une partie du nom de l'API (par exemple, "Agenda"), puis cliquez sur le nom une fois qu'il s'affiche.
Cliquez sur Activer l'API.
Fermez la console Google Cloud et revenez à l'éditeur de script.
Comment les signatures de méthodes sont-elles déterminées ?
Les services avancés utilisent généralement les mêmes objets, noms de méthodes et paramètres que les API publiques correspondantes, bien que les signatures de méthode soient traduites pour être utilisées dans Apps Script. La fonction d'autocomplétion de l'éditeur de script fournit généralement suffisamment d'informations pour vous lancer. Les règles suivantes expliquent comment Apps Script génère une signature de méthode à partir d'une API Google publique.
Les requêtes envoyées aux API Google peuvent accepter différents types de données, y compris des paramètres de chemin d'accès, des paramètres de requête, un corps de requête ou une pièce jointe d'importation de contenu multimédia. Certains services avancés peuvent également accepter des en-têtes de requête HTTP spécifiques (par exemple, le service avancé Agenda).
La signature de méthode correspondante dans Apps Script comporte les arguments suivants :
- Corps de la requête (généralement une ressource), sous forme d'objet JavaScript.
- Paramètres de chemin d'accès ou obligatoires, sous forme d'arguments individuels. Si la méthode nécessite plusieurs paramètres de chemin d'accès, ils apparaissent dans l'ordre dans lequel ils sont listés dans l'URL du point de terminaison de l'API.
- Pièce jointe d'importation de contenu multimédia, en tant qu'argument
Blob. - Paramètres facultatifs (généralement des paramètres de requête), sous la forme d'un objet JavaScript mappant les noms de paramètres à leurs valeurs.
- En-têtes de requête HTTP, sous forme d'objet JavaScript mappant les noms d'en-tête aux valeurs d'en-tête.
Si la méthode ne comporte aucun élément dans une catégorie donnée, cette partie de la signature est omise.
Tenez compte des exceptions suivantes :
- Pour les méthodes qui acceptent l'importation de contenus multimédias, le paramètre
uploadTypeest défini automatiquement. - Les méthodes nommées
deletedans l'API Google sont nomméesremovedans Apps Script, cardeleteest un mot réservé en JavaScript. - Si un service avancé est configuré pour accepter les en-têtes de requête HTTP et que vous définissez un objet JavaScript d'en-têtes de requête, vous devez également définir l'objet JavaScript de paramètres facultatifs (sur un objet vide si vous n'utilisez pas de paramètres facultatifs).
Exemple : Calendar.Events.insert
Pour créer un événement Agenda :
La documentation de l'API Google Calendar montre la structure de la requête HTTP correspondante :
- Verbe HTTP :
POST - URL de la demande :
https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events Corps de la requête : ressource Event.
Paramètres de requête :
sendUpdates,supportsAttachments, etc.
Dans Apps Script, la signature de la méthode est déterminée en réorganisant ces entrées :
- Body : ressource d'événement (objet JavaScript).
- Chemin d'accès :
calendarId(chaîne). - Paramètres facultatifs : paramètres de requête (objet JavaScript).
L'appel de méthode obtenu se présente comme suit :
const event = {
summary: 'Lunch',
location: 'Deli',
start: {
dateTime: '2026-01-01T12:00:00-05:00'
},
end: {
dateTime: '2026-01-01T13:00:00-05:00'
}
};
const calendarId = 'primary';
const optionalArgs = {
sendUpdates: 'all'
};
Calendar.Events.insert(event, calendarId, optionalArgs);
Services avancés ou HTTP ?
Chaque service Google avancé est associé à une API Google publique. Dans Apps Script, accédez à ces API à l'aide de services avancés ou en envoyant directement les requêtes API à l'aide de UrlFetch.
Si vous utilisez la méthode de service avancée, Apps Script gère le flux d'autorisation et propose la saisie semi-automatique. Activez le service avancé avant de l'utiliser.
Si vous utilisez la méthode UrlFetch pour accéder directement à l'API, vous traitez essentiellement l'API Google comme une API externe. Avec cette méthode, utilisez tous les aspects de l'API. Toutefois, vous devez gérer l'autorisation de l'API.
Le tableau suivant compare les deux méthodes :
| Fonctionnalité | Service avancé | UrlFetch (HTTP) |
|---|---|---|
| Autorisation | Géré automatiquement | Manipulation manuelle requise |
| Saisie semi-automatique | Disponible | Non disponible |
| Champ d'application des fonctionnalités | Peut être un sous-ensemble de l'API | Accès complet à toutes les fonctionnalités de l'API |
| Complexité | Plus simple | Plus complexe (nécessite de créer des en-têtes et d'analyser les réponses) |
Comparaison de code
Les exemples de code montrent la différence de complexité entre la création d'un événement d'agenda à l'aide du service avancé et à l'aide de UrlFetchApp.
Service avancé :
const event = {
summary: 'Lunch',
location: 'Deli',
start: { dateTime: '2026-01-01T12:00:00-05:00' },
end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const optionalArgs = {
sendUpdates: 'all'
};
Calendar.Events.insert(event, 'primary', optionalArgs);
UrlFetch (HTTP) :
const event = {
summary: 'Lunch',
location: 'Deli',
start: { dateTime: '2026-01-01T12:00:00-05:00' },
end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
method: 'post',
contentType: 'application/json',
headers: {
Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
},
payload: JSON.stringify(event)
};
UrlFetchApp.fetch(url, options);
Pour la méthode UrlFetchApp, spécifiez manuellement les scopes OAuth requis dans le fichier manifeste du script.
Utilisez un service avancé chaque fois que cela est possible, et n'utilisez la méthode UrlFetch que lorsque le service avancé n'est pas disponible ou ne fournit pas la fonctionnalité dont vous avez besoin.
Compatibilité avec les services avancés
Étant donné que les services avancés sont des wrappers de bas niveau pour les API Google, tout problème rencontré lors de leur utilisation est généralement lié à l'API sous-jacente, et non à Apps Script.
Si vous rencontrez un problème lors de l'utilisation d'un service avancé, signalez-le en suivant les instructions d'assistance pour l'API sous-jacente.