Apps Script-Aufgabe

Mitteilung: Application Integration ist jetzt für Ihr Google Cloud-Projekt verfügbar. Sie können jetzt Apigee Integration und Application Integration im selben Google Cloud-Projekt verwenden. Weitere Informationen

Mit der Aufgabe Apps Script können Sie Google Apps Script über Ihre Integration ausführen. Google Apps Script ist eine schnelle Plattform für die Entwicklung von Anwendungen, mit der Sie schnell und einfach Geschäftsanwendungen erstellen können. Weitere Informationen finden Sie unter Google Apps Script. Diese Aufgabe ist hilfreich, wenn Sie benutzerdefinierte Skripts ausführen oder vorhandene Skripts in Ihrer Integration wiederverwenden möchten.

Hinweis: Die Aufgabe Apps Script ist ein nicht regionaler globaler Dienst.

Vorbereitung

Bevor Sie die Apps Script-Aufgabe verwenden, führen Sie die folgenden Schritte aus:

• AppsScript API aktivieren
• OAuth 2.0-Client-ID erstellen
• Authentifizierungsprofil einrichten
• Achten Sie darauf, dass VPC Service Controls NICHT für die Apigee Integration in Ihrem Google Cloud-Projekt eingerichtet ist.
  Warnung: Cloud Functions funktioniert nicht oder funktioniert nicht mehr, wenn VPC Service Controls für Apigee Integration in Ihrer Google Cloud eingerichtet ist.

AppsScript API aktivieren

Sie müssen die AppsScript API in Ihrem Google Cloud-Projekt und in Ihrem AppsScript-Nutzerkonto aktivieren, um diese Aufgabe verwenden zu können. Informationen zum Aktivieren der AppsScript API in Ihrem Google Cloud-Projekt finden Sie unter API in einem Google Cloud-Standardprojekt aktivieren. Klicken Sie auf Einstellungen und legen Sie Google Apps Script API auf On fest, um die API in Ihrem Nutzerkonto zu aktivieren.

OAuth 2.0-Client-ID erstellen

Wenn Sie eine OAuth 2.0-Client-ID haben, können Sie diesen Schritt überspringen und mit Authentifizierungsprofil einrichten fortfahren.

Informationen zum Erstellen einer neuen OAuth-Client-ID finden Sie unter OAuth-Client-ID erstellen.

Authentifizierungsprofil einrichten

Apigee Integration verwendet das Authentifizierungsprofil, um eine Verbindung zu Google Cloud zum Bereitstellen und Ausführen des Apps Script-Projekts herzustellen. Führen Sie die folgenden Schritte aus, um ein Authentifizierungsprofil einzurichten:

Apps Script-Aufgabe hinzufügen

1. Wählen Sie in der Apigee-Benutzeroberfläche Ihre Apigee-Organisation aus.
2. Klicken Sie auf Entwickeln > Integrationen.
3. Wählen Sie eine vorhandene Integration aus oder erstellen Sie eine neue Integration, indem Sie auf Integration erstellen klicken.

   Wenn Sie eine neue Integration erstellen, gehen Sie so vor:

   1. Geben Sie im Dialogfeld Integration erstellen einen Namen und eine Beschreibung ein.
   2. Wählen Sie eine Region für die Integration aus der Liste der unterstützten Regionen aus.
   3. Klicken Sie auf Erstellen.

   Dadurch wird die Integration auf der Seite Integrationsdesigner geöffnet.

4. Klicken Sie in der Navigationsleiste Integrationsdesigner auf + Aufgabe/Trigger hinzufügen > Aufgaben, um die Liste der verfügbaren Aufgaben aufzurufen.
5. Klicken Sie auf das Element Apps Script und platzieren Sie es im Integrationseditor.

Authentifizierungsprofil erstellen

1. Klicken Sie im Designer auf das Element Apps Script, um den Aufgabenkonfigurationsbereich Apps Script aufzurufen.
2. Klicken Sie im Aufgabenkonfigurationsbereich der Apps Script-Aufgabe auf +Neues Authentifizierungsprofil.
3. Geben Sie im Dialogfeld Authentifizierungsprofil einen Namen und eine Beschreibung für das Profil ein. Legen Sie außerdem die folgenden Eigenschaften fest:
   • Authentifizierungstyp: Wählen Sie OAuth 2.0-Autorisierungscode aus.
   • Authentifizierungsendpunkt: Geben Sie https://accounts.google.com/o/oauth2/auth ein.
   • Token-Endpunkt: Geben Sie https://oauth2.googleapis.com/token ein.
   • Client-ID: Geben Sie die Client-ID ein.

     Die Client-ID ist in Ihrem Google Cloud-Projekt-Dashboard unter Anmeldedaten > OAuth 2.0-Client-IDs verfügbar.

   • Secret: Geben Sie den Clientschlüssel ein.

     Der Clientschlüssel ist in Ihrem Google Cloud-Projekt-Dashboard unter Anmeldedaten > OAuth 2.0-Client-IDs verfügbar.

   • Bereiche: Geben Sie Folgendes ein:

     https://www.googleapis.com/auth/script.projects https://www.googleapis.com/auth/script.deployments https://www.googleapis.com/auth/script.deployments.readonly https://www.googleapis.com/auth/drive.scripts https://www.googleapis.com/auth/drive https://www.googleapis.com/auth/script.external_request https://www.googleapis.com/auth/userinfo.email

     Hinweis: Mehrere Bereiche können durch ein einzelnes Leerzeichen (" ") getrennt werden.

4. Klicken Sie auf Zugriffstoken generieren und speichern.

   Sie werden zu einem Autorisierungsbildschirm weitergeleitet. Melden Sie sich an und akzeptieren Sie die auf dem Bildschirm aufgeführten Berechtigungen, um Ihr Zugriffstoken zu generieren. Wenn das Zugriffstoken generiert wurde, wird das Authentifizierungsprofil gespeichert und Sie können die Integration weiter bearbeiten.

Hinweis: Die Erstellung des Authentifizierungsprofils und die Bereitstellung des Apps Script müssen beide durch denselben Nutzer erfolgen. Sind es zwei verschiedene Nutzer, wird das Apps Script nicht ausgeführt.

Apps Script-Aufgabe konfigurieren

Führen Sie die folgenden Schritte aus, um ein Apps Script-Projekt in der Aufgabe Apps Script zu konfigurieren:

1. Klicken Sie im Aufgabenkonfigurationsbereich auf Apps Script-Projekt konfigurieren.

   Das Dialogfeld Apps Script-Konfiguration wird angezeigt.

2. Sie können eine Verknüpfung zu einem bestehenden Apps Script-Projekt erstellen oder ein neues Apps Script-Projekt erstellen.

   Durch die Konfiguration eines Apps Script-Projekts wird das Apps Script-Projekt mit Ihrer Integration in Apigee Integration verknüpft.

3. Klicken Sie auf „Speichern“.
4. Klicken Sie auf Apps Script-Projekt öffnen.

   Im Apps Script-Editor werden folgende Dateien angezeigt:

   • Run.gs: Enthält den ausführbaren Code. Schreiben Sie das Skript in die Funktion run. Diese Funktion wird aufgerufen, wenn die Apps Script-Aufgabe ausgeführt wird. In Ihrem Skript können Sie die auf Integrationsebene definierten Variablen verwenden. Informationen zur Verwendung der Integrationsvariablen finden Sie unter Integrationsvariablen verwenden.
   • Main.gs: Enthält den Initialisierungscode, um Apps Script aus Ihrer Integration auszuführen. Diese Datei darf nicht bearbeitet oder geändert werden.
   • Test.gs: Enthält den ausführbaren Code für Testläufe. Sie können Ihr Skript in die testRun-Funktion schreiben, um das Skript zu testen.

   Das Projekt muss im Format Webanwendungen bereitgestellt werden. Weitere Informationen zu den verschiedenen Bereitstellungsmodi finden Sie unter Bereitstellungen erstellen und verwalten.

Auf Integrationsvariablen zugreifen

Die Aufgabe "Apps Script" verwendet die Bibliothek AppsScriptTask, mit der Sie Integrationsvariablen in Ihrem Skript verwenden können. Die Bibliothek AppsScriptTask wird automatisch importiert und kann in der Funktion run verwendet werden.

Für den Zugriff auf eine Integrationsvariable in Ihrem Apps Script müssen Sie die Variable in Form von Aufgabenparametern an die Apps Script-Aufgabe übergeben. Aufgabenparameter sind Schlüssel/Wert-Paare, wobei Schlüssel der Name der Variablen in Ihrer AppsScript-Aufgabe ist und Wert der Name der Integrationsvariablen. Sie können einen oder mehrere Aufgabenparameter im Abschnitt Aufgabenparameter des Aufgabenkonfigurationsbereichs hinzufügen.

Wenn Sie beispielsweise eine Integrationsvariable mit dem Namen Product haben, die Sie in Ihrem Apps Script verwenden möchten, können Sie Key als ProductKey und den Wert als Product definieren. In Ihrem Apps Script können Sie dann AppsScriptTask.getTaskParameter('ProductKey') verwenden, um die Variable Product zu lesen.

Hinweis: Wenn Sie in Ihrem AppsScript eine Integrationsvariable verwenden möchten, muss die Variable der Apps Script-Aufgabe als Aufgabenparameter hinzugefügt werden.

Die Bibliothek AppsScriptTask bietet die folgenden Methoden für den Zugriff auf die Integrationsvariablen:

• setIntegrationVariable
• getTaskParameter

Funktionsname	Beschreibung	Nutzung
setIntegrationVariable	Legt den angegebenen Wert auf die Variable fest.	Syntax: setIntegrationVariable(value,value) Beispiel: // Write to an Integer variable AppsScriptTask.setIntegrationVariable('EmployeeIDKey','456');
getTaskParameter	Ruft den Wert einer Variablen ab.	Syntax: getTaskParameter(value) Beispiel: // Read an integration variable AppsScriptTask.getTaskParameter('EmployeeIDKey');

Wenn Sie alle Funktionen der AppsScriptTask-Bibliothek aufrufen möchten, bewegen Sie im Apps Script-Editor den Mauszeiger auf den Menüpunkt AppsScriptTask und klicken Sie dann auf das Dreipunkt-Menü > In neuem Tab öffnen.

Apps Script testen

Bevor Sie Ihre Integration veröffentlichen, können Sie Ihr Skript mit der Funktion testRun testen, die in der Datei Test.gs verfügbar ist. Schreiben Sie Ihren Testcode in der Funktion testRun mithilfe der Bibliothek AppsScriptTaskTest. Mit dieser Bibliothek können Sie assertion-basierte Testfälle ausführen. Sie wird automatisch importiert, um sie in der Funktion testRun zu verwenden.

Wenn Sie alle Funktionen der AppsScriptTaskTest-Bibliothek aufrufen möchten, bewegen Sie im Apps Script-Editor den Mauszeiger auf den Menüpunkt AppsScriptTaskTest und klicken Sie dann auf das Dreipunkt-Menü > In neuem Tab öffnen.

Das folgende Beispiel zeigt die Verwendung der Funktionen der Bibliothek AppsScriptTaskTest.

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('myCustomTest');

  // Add a task parameter that references an integration variable with the value 5
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, 'input', '$input$', 5);

  // Add a task parameter that references an integration variable
  AppsScriptTaskTest.createReference(req, 'output', '$output$');

  // Run the task(assuming the task increments the input by 1) and get the response
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariable(res, 'output', true);
  AppsScriptTaskTest.containsIntegrationVariable(res, 'someOtherIntegrtionVariable', false);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, 'output', 6);
}

Das folgende Beispiel zeigt, wie Sie in der Methode testRun auf JSON- und Array-Variablen zugreifen:

function testRun(){

  // Create a new request
  let req = AppsScriptTaskTest.createNewTestRequest('json-test');

  // Add a task parameter that references a JSON integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "emp", "employee", {name:"snape", age:35});

  // Add a task parameter that references an array integration variable
  AppsScriptTaskTest.setIntegrationVariableAndCreateReference(req, "arr", "array", ["A", "B", "C"]);

  // Run the task and get the response
  // Assume that the run method increases the age of the employee by 5 and appends a new element in the array
  let res = AppsScriptTaskTest.runTest(req, executeScript);

  // Check the response for the expected integration variable and its corresponding values
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "employee", {name:"snape", age:40});
  AppsScriptTaskTest.containsIntegrationVariable(res, "array", true);
  AppsScriptTaskTest.containsIntegrationVariableWithValue(res, "array", ["A", "B", "C", "D"]);
}

Nach dem Ausführen der Testläufe können Sie sich die Assertions im Ausführungslog ansehen. Klicken Sie im Menü auf Ausführungslog, um die Logs aufzurufen.

Best Practices

Wir empfehlen, die Apps Script-Aufgabe nicht zu verwenden, wenn Sie eine Latenz von weniger als 1 bis 2 Sekunden für die Aufgabe in Ihrer Integration benötigen.

Darüber hinaus empfehlen wir, Ihre gesamte Logik in einer einzigen Apps Script-Aufgabe zu codieren, anstatt mehrere Apps Script-Aufgaben zu verketten, um Leistungsengpässe zu minimieren.

Informationen zu den Nutzungsbeschränkungen für die Aufgabe Apps Script finden Sie unter Nutzungslimits.

Hinweise

Wenn Sie die Aufgabe „Apps Script“ in Ihr Integrationsdesign einbinden, beachten Sie die folgenden Systembeschränkungen:

• Maximale Anzahl aktiver Bereitstellungen für ein AppsScript: 50
• Abfragen pro Sekunde (QPS) für ausführbare API-Anfragen: 5.000/Min.
• Abfragen pro Sekunde (QPS) für Webapp-Bereitstellungen: 5.000/Min.
• Latenz für ausführbare API-Dateien: 1,5 Sek.
• Latenz für Web-App: 2,5 Sek.
• Maximale kumulative Größe aller Integrationsvariablen in einem AppsScript: 15 MB

Fehlerbehebungsstrategie

Eine Strategie zur Fehlerbehandlung für eine Aufgabe legt die Aktion fest, die ausgeführt werden soll, wenn die Aufgabe aufgrund eines temporären Fehlers fehlschlägt. Informationen zur Verwendung einer Fehlerbehandlungsstrategie und zu den verschiedenen Arten von Fehlerbehandlungsstrategien finden Sie unter Strategien zur Fehlerbehebung.