Service HTML: communication avec les fonctions du serveur (original) (raw)
google.script.run est une API JavaScript côté client asynchrone qui permet aux pages de service HTML d'appeler des fonctions Apps Script côté serveur. L'exemple suivant montre la fonctionnalité la plus basique de google.script.run : l'appel d'une fonction sur le serveur à partir de JavaScript côté client.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }
function doSomething() { Logger.log('I was called!'); }
Index.html
Si vous déployez ce script en tant qu'application Web et que vous accédez à son URL, vous ne verrez rien, mais si vous consultez les journaux, vous verrez que la fonction de serveur doSomething() a été appelée.
Les appels côté client aux fonctions côté serveur sont asynchrones: une fois que le navigateur a demandé au serveur d'exécuter la fonction doSomething(), il passe immédiatement à la ligne de code suivante sans attendre de réponse. Cela signifie que les appels de fonction du serveur peuvent ne pas s'exécuter dans l'ordre prévu. Si vous effectuez deux appels de fonction en même temps, il n'est pas possible de savoir quelle fonction s'exécutera en premier. Le résultat peut varier à chaque fois que vous chargez la page. Dans cette situation, les gestionnaires de succès et les gestionnaires d'échec permettent de contrôler le flux de votre code.
L'API google.script.run autorise 10 appels simultanés aux fonctions du serveur. Si vous effectuez un 11e appel alors que 10 sont toujours en cours d'exécution, la fonction du serveur sera retardée jusqu'à ce que l'une des 10 places soit libérée. En pratique, vous devriez rarement avoir à penser à cette restriction, d'autant plus que la plupart des navigateurs limitent déjà le nombre de requêtes simultanées au même serveur à un nombre inférieur à 10. Dans Firefox, par exemple, la limite est de six. De même, la plupart des navigateurs retardent les requêtes de serveur excédentaires jusqu'à ce qu'une des requêtes existantes soit terminée.
Paramètres et valeurs renvoyées
Vous pouvez appeler une fonction de serveur avec des paramètres à partir du client. De même, une fonction de serveur peut renvoyer une valeur au client en tant que paramètre transmis à un gestionnaire de réussite.
Les paramètres et valeurs de retour légaux sont des primitives JavaScript telles que Number, Boolean, String ou null, ainsi que des objets et des tableaux JavaScript composés de primitives, d'objets et de tableaux. Un élément form sur la page est également autorisé en tant que paramètre, mais il doit être le seul paramètre de la fonction et n'est pas autorisé en tant que valeur renvoyée. Les requêtes échouent si vous essayez de transmettre un élément Date, Function ou DOM en plus d'un form, ou un autre type interdit, y compris des types interdits dans des objets ou des tableaux. Les objets qui créent des références circulaires échoueront également, et les champs non définis dans les tableaux deviendront null.
Notez qu'un objet transmis au serveur devient une copie de l'original. Si une fonction de serveur reçoit un objet et modifie ses propriétés, les propriétés du client ne sont pas affectées.
Gestionnaires de réussite
Étant donné que le code côté client passe à la ligne suivante sans attendre la fin d'un appel de serveur, withSuccessHandler(function) vous permet de spécifier une fonction de rappel côté client à exécuter lorsque le serveur répond. Si la fonction du serveur renvoie une valeur, l'API transmet la valeur à la nouvelle fonction en tant que paramètre.
L'exemple suivant affiche une alerte du navigateur lorsque le serveur répond. Notez que cet exemple de code nécessite une autorisation, car la fonction côté serveur accède à votre compte Gmail. Le moyen le plus simple d'autoriser le script consiste à exécuter manuellement la fonction getUnreadEmails() depuis l'éditeur de script une fois avant de charger la page. Vous pouvez également choisir de l'exécuter en tant qu'utilisateur accédant à l'application Web lorsque vous déployez l'application Web. Dans ce cas, vous serez invité à autoriser l'application lorsque vous la chargerez.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }
function getUnreadEmails() { return GmailApp.getInboxUnreadCount(); }
Index.html
Formulaires
Si vous appelez une fonction de serveur avec un élément form en tant que paramètre, le formulaire devient un seul objet avec des noms de champ comme clés et des valeurs de champ comme valeurs. Les valeurs sont toutes converties en chaînes, à l'exception du contenu des champs d'entrée de fichier, qui deviennent des objets Blob.
Cet exemple traite un formulaire, y compris un champ de saisie de fichier, sans recharger la page. Il importe le fichier dans Google Drive, puis imprime l'URL du fichier sur la page côté client. Dans le gestionnaire onsubmit, le mot clé this fait référence au formulaire lui-même. Notez que lors du chargement de tous les formulaires de la page, l'action d'envoi par défaut est désactivée par preventFormSubmit. Cela empêche la page d'être redirigée vers une URL inexacte en cas d'exception.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }
function processForm(formObject) { var formBlob = formObject.myFile; var driveFile = DriveApp.createFile(formBlob); return driveFile.getUrl(); }