Services Google avancés

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 lorsqu'ils utilisent leurs interfaces HTTP. Les services avancés sont essentiellement 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. 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, recherchez 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é, il vous suffit de vous y connecter comme à n'importe quelle autre API externe.

Services avancés ou HTTP ?

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

Si vous utilisez la méthode de service avancé, Apps Script gère le flux d'autorisation et propose une assistance pour l'autocomplétion. Toutefois, vous devez activer le service avancé avant de pouvoir l'utiliser. De plus, 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 essentiellement l'API Google comme une API externe. Cette méthode permet d'utiliser tous les aspects de l'API. Cependant, vous devez gérer vous-même l'autorisation de l'API. Vous devez également créer les en-têtes nécessaires et analyser les réponses de l'API.

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

Conditions requises

Pour pouvoir utiliser un service avancé, vous devez remplir les conditions 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éé le 8 avril 2019 ou après, l'API est activée automatiquement après l'activation du service avancé et l'enregistrement du projet de script. Si vous ne l'avez pas encore fait, vous serez peut-être également invité à accepter les conditions d'utilisation de Google Cloud 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. Pour effectuer cette modification, vous devez disposer des droits de modification sur le projet GCP.

Pour en savoir plus, consultez Projets Cloud Platform.

Activer les services avancés

Pour utiliser un service Google avancé, suivez ces instructions :

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

Remarque : Si vous utilisez un projet GCP standard (ou un ancien projet GCP par défaut créé avant le 8 avril 2019), vous devez également activer manuellement l'API correspondant au service avancé. Activez l'API en procédant comme suit :

1. Ouvrez le projet GCP associé à votre script dans la console Google Cloud.
2. En haut de la console, cliquez dans la barre de recherche et saisissez une partie du nom de l'API (par exemple, "Calendar"), puis cliquez sur le nom une fois qu'il s'affiche.
3. Sur l'écran suivant, cliquez sur Activer l'API.
4. Fermez la console Google Cloud et revenez à l'éditeur de script. Cliquez sur OK dans la boîte de dialogue.

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

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éthodes 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 aider à vous lancer. Toutefois, 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 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 et/ou une pièce jointe de type import 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 Google Apps Script comporte les arguments suivants :

1. Corps de la requête (généralement une ressource), sous forme d'objet JavaScript.
2. Paramètres de chemin d'accès ou obligatoires, sous forme d'arguments individuels.
3. Pièce jointe d'importation de contenu multimédia, en tant qu'argument Blob.
4. Paramètres facultatifs, sous la forme d'un objet JavaScript mappant les noms de paramètres aux valeurs.
5. 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.

Il existe quelques exceptions spéciales à connaître :

• Pour les méthodes qui acceptent l'importation de contenus multimédias, le paramètre uploadType est défini automatiquement.
• Les méthodes nommées delete dans l'API Google sont nommées remove dans Apps Script, car delete est 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).

Compatibilité avec les services avancés

Les services avancés ne sont que des wrappers de bas niveau qui permettent d'utiliser des API Google dans Apps Script. Par conséquent, tout problème rencontré lors de leur utilisation est généralement lié à l'API sous-jacente, et non à Apps Script lui-même.

Si vous rencontrez un problème lors de l'utilisation d'un service avancé, vous devez le signaler en suivant les instructions d'assistance pour l'API sous-jacente. Des liens vers ces instructions d'assistance sont fournis dans chaque guide de service avancé de la section Référence Apps Script.