Services Google avancés

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Les services avancés d'Apps Script permettent aux développeurs expérimentés de se connecter à certaines API Google publiques avec moins de configuration que d'utiliser leurs interfaces HTTP. Les services avancés sont essentiellement des wrappers légers autour de ces API Google. Ils fonctionnent de la même manière que les services intégrés d'Apps Script, par exemple pour la saisie semi-automatique, et Apps Script gère automatiquement le flux d'autorisation. Toutefois, vous devez activer un service avancé avant de pouvoir l'utiliser dans un script.

Pour savoir quelles API Google sont disponibles en tant que services avancés, consultez la section Services Google avancés dans la documentation de référence. Si vous souhaitez utiliser une API Google qui n'est pas disponible en tant que service avancé, connectez-vous simplement à celle-ci comme n'importe quelle autre API externe.

Services avancés ou HTTP ?

Chacun des services avancés de Google est associé à une API Google publique. Dans Apps Script, vous pouvez accéder à ces API via des services avancés ou en envoyant simplement des requêtes API directement à l'aide de UrlFetch.

Si vous utilisez la méthode de service avancée, Apps Script gère le flux d'autorisation et offre une assistance concernant la saisie semi-automatique. Toutefois, vous devez activer le service avancé avant de pouvoir l'utiliser. En outre, certains services avancés ne fournissent qu'un sous-ensemble des fonctionnalités disponibles dans l'API.

Si vous utilisez la méthode UrlFetch pour accéder directement à l'API, vous traitez l'API Google comme une API externe. Avec cette méthode, tous les aspects de l'API peuvent être utilisés. Toutefois, vous devrez gérer vous-même l'autorisation de l'API. Vous devez également construire les en-têtes nécessaires et analyser les réponses de l'API.

En règle générale, il est plus facile d'utiliser un service avancé lorsque cela est possible et de n'utiliser la méthode UrlFetch que s'il ne fournit pas les fonctionnalités dont vous avez besoin.

Conditions requises

Avant de pouvoir utiliser un service avancé, vous devez répondre aux exigences suivantes:

  1. Vous devez activer le service avancé dans votre projet de script.
  2. Vous devez vous assurer que l'API correspondant au service avancé est activée dans le projet Cloud Platform (GCP) utilisé par votre script.

    Si votre projet de script utilise un projet GCP par défaut créé à compter du 8 avril 2019, l'API est activée automatiquement une fois le service avancé activé et enregistré le projet de script. Si vous ne l'avez pas déjà fait, vous pouvez également être invité à accepter les conditions d'utilisation de Google Cloud Platform et des API Google.

    Si votre projet de script utilise un projet GCP standard ou un ancien projet GCP par défaut, vous devez activer manuellement l'API correspondante du service avancé dans le projet GCP. Vous devez être autorisé à modifier le projet GCP pour effectuer cette modification.

Pour en savoir plus, consultez la section Projets Cloud Platform.

Activer les services avancés

Pour utiliser un service Google avancé, procédez comme suit:

  1. Ouvrez le projet Apps Script.
  2. À gauche, cliquez sur Éditeur .
  3. À gauche, à côté de Services, cliquez sur Ajouter un service .
  4. Sélectionnez un service Google avancé, puis cliquez sur Ajouter.

Une fois que vous avez activé un service avancé, il est disponible dans la saisie semi-automatique.

Comment les signatures de méthode sont-elles déterminées ?

Les services avancés utilisent généralement les mêmes objets, noms de méthode 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 de saisie semi-automatique de l'éditeur de scripts fournit généralement suffisamment d'informations pour commencer, mais les règles ci-dessous expliquent comment Apps Script génère une signature de méthode à partir d'une API Google publique.

Les requêtes adressé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 et/ou une pièce jointe d'importation multimédia. Certains services avancés peuvent également accepter des en-têtes de requêtes HTTP spécifiques (par exemple, le service avancé d'Agenda).

La signature de méthode correspondante dans Google Apps Script contient les arguments suivants:

  1. Corps de la requête (généralement une ressource) en tant qu'objet JavaScript.
  2. Chemin ou paramètres obligatoires en tant qu'arguments individuels.
  3. Le rattachement d'importation multimédia, en tant qu'argument Blob.
  4. Paramètres facultatifs, en tant qu'objet JavaScript mappant des noms de paramètres avec des valeurs.
  5. En-têtes de requêtes HTTP, en tant qu'objet JavaScript mappant des noms d'en-têtes avec des 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.

Voici quelques exceptions:

  • Pour les méthodes qui acceptent une importation multimédia, le paramètre uploadType est défini automatiquement.
  • Les méthodes nommées delete dans l'API Google s'appellent remove dans Apps Script, car delete est un terme réservé en JavaScript.
  • Si un service avancé est configuré pour accepter les en-têtes de requêtes HTTP et que vous définissez un objet JavaScript d'en-têtes de requête, vous devez également définir l'objet JavaScript des paramètres facultatifs (sur un objet vide si vous n'utilisez pas de paramètres facultatifs).

Assistance pour les services avancés

Les services avancés sont de petits wrappers qui permettent d'utiliser des API Google dans Apps Script. Par conséquent, tout problème rencontré lors de leur utilisation concerne généralement l'API sous-jacente, et non pas Apps Script.

Si vous rencontrez un problème lors de l'utilisation d'un service avancé, vous devez le signaler à l'aide des instructions d'assistance de l'API sous-jacente. Vous trouverez des liens vers ces instructions d'assistance dans chaque guide de service avancé de la section Documentation de référence sur Apps Script.