Daten über einen Action Hub teilen

Neben der Bereitstellung von Inhalten an die integrierten Ziele von Looker können Sie mit Aktionen – auch Integrationen genannt – Inhalte über einen Action Hub-Server an Drittanbieterdienste senden, die in Looker eingebunden sind.

Auf dieser Seite werden die Optionen zum Erstellen benutzerdefinierter Aktionen beschrieben. Diese können Sie entweder dem Looker Action Hub hinzufügen oder Ihrem eigenen Private Action Hub-Server hinzufügen. Auf dieser Seite wird auch beschrieben, wie Sie einen lokalen Action Hub-Server einrichten, um Ihre benutzerdefinierten Aktionen zu testen oder einen Private Action Hub-Server auszuführen.

Zum Verwenden von Aktionen haben Sie folgende Möglichkeiten:

Sobald die Aktion dem Action Hub hinzugefügt wurde, kann ein Looker-Administrator sie zur Bereitstellung von Looker-Inhalten an diese Dienste enable.

Sie können auch mehrere Action Hubs einrichten, wenn Sie die Integrationen von Looker über den Looker Action Hub verwenden und auch Ihre eigenen privaten oder benutzerdefinierten Aktionen hosten möchten. Die Aktionen für jeden Action Hub würden auf der Seite Aktionen im Admin-Bereich angezeigt.

Der Looker Action Hub

Looker hostet und stellt den Looker Action Hub zur Verfügung, einen zustandslosen Server, auf dem die Looker Action API implementiert ist und beliebte Aktionen verfügbar gemacht werden. Alle Daten, die Ihre Nutzer über eine Aktion senden, werden vorübergehend auf dem Looker Action Hub-Server und nicht in Ihrer Looker-Instanz verarbeitet.

Looker ist bereits in mehrere Dienste integriert. Auf der Dokumentationsseite Administratoreinstellungen – Aktionen erfahren Sie, wie Sie diese vorhandenen Dienste aktivieren können.

Anforderungen für Looker Action Hub

Der Looker Action Hub muss API-Anfragen auf folgende Arten senden und empfangen können:

Wenn Ihre Looker-Bereitstellung diese Anfragen nicht berücksichtigen kann oder die Funktion IP-Zulassungsliste für Ihre Looker-Instanz aktiviert ist, können Sie einen lokalen Action Hub-Server einrichten, um private Looker-Integrationen oder benutzerdefinierte Aktionen bereitzustellen. Administratoren von vom Kunden gehosteten Instanzen können auch einen lokalen Aktionsserver speziell für OAuth- und Streaming-Aktionen bereitstellen.

Anfragen von der Looker-Instanz an das Looker Action Hub-Netzwerk

Anfragen an actions.looker.com werden in eine dynamische IP-Adresse aufgelöst. Ausgehende Anfragen von der Looker-Instanz müssen die folgenden Endpunkte erreichen können:

actions.looker.com/
actions.looker.com/actions/<name>/execute
actions.looker.com/actions/<name>/form

Dabei ist name der programmatische Name der Aktion.

Anfragen vom Browser des Looker-Benutzers an das Looker Action Hub-Netzwerk

Der Browser des Looker-Nutzers muss Anfragen an die folgenden Looker Action Hub-Endpunkte senden können (für OAuth):

actions.looker.com/actions/<name>/oauth

Dabei ist name der programmatische Name der Aktion.

Anfragen vom Looker Action Hub-Netzwerk an die Looker-Instanz

Der Looker Action Hub muss Anfragen für Aktionen an die Looker-Instanz senden, die gestreamte Ergebnisse unterstützen oder OAuth verwenden.

Mit einer Streamingaktion kann die Aktion Abfragen verarbeiten, die Alle Ergebnisse liefern. Für OAuth-fähige Aktionen wird die nutzerspezifische Authentifizierung über OAuth 2.0-Abläufe verwendet. OAuth-Aktionen müssen Nutzeranmeldedaten in ihrer Looker-Quellinstanz speichern, da der Looker Action Hub zustandslos und mehrmandantenfähig ist. Außerdem werden keine nutzerspezifischen Anmeldedaten jeglicher Art gespeichert.

Die Anfragen vom Looker Action Hub an eine Looker-Instanz haben die folgenden Formen:

GET <host_looker_url>/downloads/<random_40_char_token>
POST <host_looker_url>/action_hub_state/<random_40_char_token>

Diese URLs werden direkt in der Looker-Instanz generiert, bevor sie an den Looker Action Hub gesendet werden. Aus diesem Grund muss der Looker Action Hub in der Lage sein, die <host_looker_url> in eine IP-Adresse aufzulösen und Anfragen an das Netzwerk zu senden, in dem sich Ihre Looker-Instanz befindet.

Der Looker Action Hub hat statische IP-Adressen für ausgehenden Traffic, von denen die Anfragen immer stammen: 35.153.89.114, 104.196.138.163 und 35.169.42.87. Administratoren von von Looker gehosteten Instanzen, die die IP-Zulassungsliste aktiviert haben, müssen diese IP-Adressen hinzufügen, um Aktionen zu verwenden, die gestreamte Ergebnisse unterstützen oder OAuth verwenden.

Hinweise zu vom Kunden gehosteten Instanzen

Damit Sie Looker-Integrationen verwenden können, muss der Looker Action Hub mit der Looker-Instanz kommunizieren können und diese Anforderungen erfüllen. Bei vom Kunden gehosteten Looker-Instanzen ist dies aus verschiedenen Gründen nicht immer möglich. Wenn eine bidirektionale Kommunikation zwischen dem Looker Action Hub und der Looker-Instanz nicht möglich ist, kann es zu unerwartetem oder unerwünschtem Verhalten beim Looker Action Hub kommen, z. B. aufhängenden Abfragen oder nicht verfügbaren Aktionen.

Um das potenzielle Problem zu beheben, dass der Looker Action Hub nicht mit der Looker-Instanz kommunizieren kann, können Looker-Administratoren eine der Lösungen implementieren, die weiter unten auf dieser Seite angezeigt werden. Die geeignete Lösung oder Kombination von Lösungen hängt von der Architektur der Looker-Instanz ab:

  • Wenn die vom Kunden gehostete Instanz nicht vom Looker Action Hub aufgelöst werden kann – der Looker Action Hub also keine Anfragen von der Looker-Instanz empfangen kann –, können sich Looker-Administratoren an einen Google Cloud-Vertriebsexperten wenden, um das public_host_url-Lizenzfeature zu aktivieren. Mit dieser Lizenzfunktion wird die Startoption --public-host-url sichtbar, mit der Administratoren einen auflösbaren <public_host_url>-Hostnamen angeben können, der sich von der Instanz <host_looker_url> unterscheidet. public_host_url überschreibt den Hostnamen für bestimmte Looker Action Hub-Callback-URLs und leitet diese Callback-URLs über einen Reverse-Proxy weiter, bei dem die public_host_url als öffentlich auflösbarer Name verwendet wird. Dieser Reverse-Proxy akzeptiert nur Anfragen von statischen ausgehenden IP-Adressen für den Looker Action Hub. Looker-Administratoren, die diese Methode verwenden, müssen die IP-Adressen für ausgehenden Traffic, von denen der Looker Action Hub Anfragen an die Looker-Instanz sendet, auf die Zulassungsliste setzen: 35.153.89.114, 104.196.138.163 und 35.169.42.87.

  • Wenn die URL der vom Kunden gehosteten Instanz von der Looker-Instanz auflösbar ist, der Looker Action Hub aber keine Anfragen an die Looker-Instanz senden kann, können Nutzer möglicherweise keine Aktionen konfigurieren oder verwenden, die gestreamte Ergebnisse unterstützen oder OAuth verwenden. Um dieses Problem zu beheben, müssen Looker-Administratoren die IP-Adressen für ausgehenden Traffic, von denen der Looker Action Hub Anfragen an die Looker-Instanz sendet, auf die Zulassungsliste setzen: 35.153.89.114, 104.196.138.163 und 35.169.42.87.

  • Wenn keine der oben genannten Lösungen für die Looker-Instanzarchitektur geeignet ist, können Looker-Administratoren einen vom Kunden gehosteten Action Hub für alle Aktionen oder nur für Aktionen bereitstellen, die gestreamte Ergebnisse unterstützen oder OAuth verwenden.

  • Wenn Sie einen vom Kunden gehosteten Action Hub bereitstellen möchten, müssen Sie dafür sorgen, dass die JAR-Datei auf einem öffentlichen Server gehostet wird, damit der Looker Action Hub mit ihr kommunizieren kann. Diese Lösung wird jedoch nicht empfohlen.

Außerdem können die OAuth- und Streaming-Aktionen auf einer vom Kunden gehosteten Looker-Instanz möglicherweise nicht verwendet werden, wenn die Instanz ein SSL-Zertifikat verwendet, das von einer Zertifizierungsstelle ausgestellt wurde, die nicht in dieser Liste der Root-Zertifikate enthalten ist.

Benutzerdefinierte Aktion erstellen

In diesem Abschnitt werden die Schritte zum Schreiben und Testen einer benutzerdefinierten Aktion mit dem Quellcode von Looker Action Hub beschrieben. Funktionscodebeispiele finden Sie in den vorhandenen Aktionen im looker-open-source/actions-Repository in GitHub.

So erstellen Sie eine benutzerdefinierte Aktion:

  1. Entwicklungs-Repository einrichten
  2. Aktion schreiben
  3. Aktion testen
  4. Aktion veröffentlichen und aktivieren, entweder im Looker Action Hub oder auf Ihrem eigenen Private Action Hub-Server

Wie bei jeder Aktion müssen Sie möglicherweise Ihre LookML-Modelle mit bestimmten Parametern konfigurieren, bevor Sie die Aktion zur Bereitstellung Ihrer Daten verwenden können.

Entwicklungs-Repository einrichten

Der Looker Action Hub ist ein Node.js-Server, der in TypeScript geschrieben ist, einer kleinen Schicht auf modernem JavaScript, die Typinformationen hinzufügt, um Programmierfehler zu erkennen. Wenn Sie mit JavaScript vertraut sind, sollten Sie den Großteil der TypeScript-Sprache bereits kennen.

Zum Ausführen des Looker Action Hub ist die folgende Software erforderlich:

  • Node.js
  • Node Version Manager (NVM – zur Auswahl der richtigen Node.js-Version)
  • Yarn (zur Verwaltung von Abhängigkeiten)

Nach der Installation der erforderlichen Software können Sie Ihre Entwicklungsumgebung einrichten. Im folgenden Beispiel wird Git verwendet.

  1. Klonen Sie das looker-open-source/actions-Repository lokal:

    git clone git@github.com:looker-open-source/actions.git

  2. Erstellen Sie im Verzeichnis actions/src/actions ein Verzeichnis mit dem Namen Ihrer Aktion. Beispiel:

    mkdir actions/src/actions/my_action

  3. Beginnen Sie damit, Ihr Verzeichnis mit den Dateien zu füllen, die Sie zum Ausführen der Aktion benötigen. Eine beispielhafte Dateistruktur findest du im GitHub-Repository für Aktionen.

Looker empfiehlt außerdem, Folgendes hinzuzufügen:

  • Eine INFODATEI zur Erläuterung des Zwecks und der Mittel der Authentifizierung für Ihre Aktion
  • Ein PNG-Symbol, das im Looker Action Hub (oder im privaten Action Hub auf Ihrer Looker-Instanz) und in den Looker-Datenbereitstellungsfenstern angezeigt wird
  • Alle Dateien für Tests, die Sie mit Ihrem Aktionscode ausführen möchten – dies unterscheidet sich vom Testen Ihrer Aktion.

Aktion schreiben

Eine Designanforderung für den Looker Action Hub-Server ist, dass er vollständig zustandslos bleibt. Daher dürfen keine Informationen in der Aktionsanwendung oder im Aktionsdienst gespeichert werden. Alle Informationen, die zum Ausführen der Aktion erforderlich sind, müssen in den Anfrageaufrufen der Aktionsdatei angegeben werden.

Der genaue Inhalt der Aktionsdatei richtet sich nach dem Dienst, dem Typ oder der Ebene, auf der die Aktion ausgeführt wird, und von den Daten- oder Visualisierungsformaten, die angegeben werden müssen. Die Aktion kann auch für OAuth 2.0-Autorisierungsabläufe konfiguriert werden.

Aktionsdateien basieren auf der API-Methode /execute. Bei Looker API-Anfragen wird jedes Mal ein DataActionRequest übergeben, wenn ein Nutzer die Aktion in Looker ausführt. DataActionRequest enthält alle Daten und Metadaten, die zum Ausführen der Aktion erforderlich sind. Außerdem ist eine /form-Methode verfügbar, mit der zusätzliche Informationen vom Nutzer erfasst werden können, bevor dieser die Aktion ausführt. Die Felder, die Sie im /form angeben, werden im Pop-up Senden oder Planen angezeigt, wenn Nutzer die Aktion als Ziel für ihre Datenübermittlung auswählen.

Nehmen Sie beim Schreiben der Aktionsdatei mindestens die folgenden als Erforderlich gekennzeichneten Parameter in Ihre Aktionsdefinition auf:

Parameter Erforderlich Beschreibung Datentyp
name Yes Ein eindeutiger Name für die Aktion. Er sollte für alle Aktionen im Looker Action Hub eindeutig sein. String
url Yes Eine absolute URL des Endpunkts /execute für diese Aktion. String
label Yes Ein für Menschen lesbares Label für die Aktion. String
supportedActionTypes Yes Eine Liste der Aktionstypen, die von der Aktion unterstützt werden. Gültige Werte sind "cell", "query" und "dashboard". String
formURL Nein Eine absolute URL des Endpunkts /form für diese Aktion. String
description Nein Beschreibung der Aktion. String
params Nein Array mit parameters für die Aktion. Geben Sie für jeden Parameter den Namen, das Label und die Beschreibung im Stringformat an. Dies sind die Felder, die auf der Aktivierungsseite der Aktion im Admin-Bereich angezeigt werden. Wenn Sie festlegen möchten, wie Nutzer Daten an ein Aktionsziel senden können, können Sie ein Nutzerattribut angeben, für das ein Nutzer einen definierten Wert haben muss. parameters
supportedFormats Nein Eine Liste der Datenformate, die von der Aktion unterstützt werden. Gültige Werte sind "txt", "csv", "inline_json", "json", "json_detail", "json_detail_lite_stream", "xlsx", "html", "wysiwyg_pdf", "assembled_pdf", and "wysiwyg_png". String
supportedFormattings Nein Eine Liste der von der Aktion unterstützten Formatierungsoptionen. Gültige Werte sind "formatted" und "unformatted". String
supportedVisualizationFormattings Nein Eine Liste der von der Aktion unterstützten Formatierungsoptionen für Visualisierungen. Gültige Werte sind "apply" und "noapply". String
iconName Nein Ein Daten-URI, der ein Symbolbild für die Aktion darstellt. String
requiredFields Nein Eine Liste mit Beschreibungen der Pflichtfelder, mit denen diese Aktion kompatibel ist. Wenn diese Liste mehrere Einträge enthält, sind für die Aktion mehrere Felder erforderlich. RequiredField
supportedDownloadSettings Nein Boolescher Wert, der bestimmt, ob die Aktion eine einmalige Download-URL sendet, um das unbegrenzte Streaming von Daten zu ermöglichen. Der Parameter wird vom Parameter usesStreaming festgelegt, bei dem es sich um einen booleschen true/false-Parameter handelt. Wenn usesStreaming = true, dann supportedDownloadSettings = url. Wenn usesStreaming = false, dann supportedDownloadSettings = push. Boolesch
usesOAuth Nein Boolescher Wert, der bestimmt, ob die Aktion eine OAuth-Aktion ist. Damit wird festgelegt, ob der Aktion ein einmalig verwendeter Link gesendet wird, über den sich state für einen bestimmten Nutzer für diese Aktion festlegen lässt. Boolesch
usesStreaming Nein Ein boolescher Wert, der bestimmt, ob die Aktion gestreamte Abfrageergebnisse unterstützt. Prüfen Sie in der Liste der integrierten Dienste die Spalte Verwendet Datenstreaming (Ja/Nein). Für Aktionen, bei denen Ergebnisse gestreamt werden, ist möglicherweise die Konfiguration eines lokalen Action Hub-Servers erforderlich. Weitere Informationen finden Sie auf der Seite Lokalen Action Hub für Aktionen mit OAuth oder Streaming einrichten. Boolesch
minimumSupportedVersion Nein Die Looker-Mindestversion, in der die Aktion in der Action Hub-Liste im Bereich Admin angezeigt wird. String

Beispiele aus den Looker Action Hub-Aktionen finden Sie auf GitHub zu Referenzzwecken.

Unterstützte Aktionstypen

Looker unterstützt drei Aktionstypen, wie im supportedActionTypes-Parameter Ihrer Aktion angegeben: Abfrage, Zelle und Dashboard.

  • Aktion auf Anfrageebene:Dies ist eine Aktion, bei der eine vollständige Anfrage gesendet wird. Die Aktion segmentieren ist beispielsweise eine Aktion auf Suchanfragenebene.
  • Aktion auf Zellenebene:Mit einer Aktion auf Zellenebene wird der Wert einer einzelnen, spezifischen Zelle in einer Datentabelle gesendet. Dieser Aktionstyp unterscheidet sich von Datenaktionen, die mit dem Parameter action für Dimensionen oder Messwerte definiert werden können. Zum Senden von Informationen aus einer bestimmten Zelle in einer Tabelle verwendet Looker Tags, um den entsprechenden Zellen Aktionen zuzuordnen. Für Aktionen muss angegeben werden, welche Tags in requiredFields unterstützt werden. Damit Aktionen und Felder zugeordnet werden können, müssen Sie in LookML-Feldern angeben, welchen Tags sie mit dem LookML-Parameter tags zugeordnet werden. Die Twilio-Nachrichtenaktion verwendet beispielsweise ein phone-Tag, damit LookML-Entwickler steuern können, für welche Telefonnummernfelder die Twilio-Aktion angezeigt wird.
  • Aktion auf Dashboardebene:Mit einer Aktion auf Dashboardebene kann ein Bild eines Dashboards gesendet werden. Die SendGrid-Aktion sendet beispielsweise Dashboard-Bilder per E-Mail.

Nutzerattribute zu benutzerdefinierten Aktionen hinzufügen

Bei benutzerdefinierten Aktionen können Sie dem Parameter params Ihrer Aktionsdatei Nutzerattribute hinzufügen. Wenn der Parameter erforderlich ist, muss für jeden Nutzer neben der Berechtigung send_to_integration ein Wert für dieses Attribut in seinem Nutzerkonto oder für eine Nutzergruppe definiert sein, der er angehört. Nur dann kann die Aktion beim Senden oder Planen von Inhalten als Zieloption angezeigt werden.

So fügen Sie Ihrer Aktion ein Nutzerattribut hinzu:

  1. Ein Looker-Administrator muss möglicherweise das Nutzerattribut erstellen, das dem user_attribute_param entspricht, falls es noch nicht vorhanden ist.
  2. Legen Sie einen gültigen Wert für das Nutzerattribut für die Nutzer oder Nutzergruppen fest, die Inhalte an das Aktionsziel senden müssen. (Diese Nutzer müssen außerdem die Berechtigung send_to_integration haben.)
  3. Der Parameter params steht für die Formularfelder, die ein Looker-Administrator auf der Aktivierungsseite der Aktion in der Liste Aktionen im Bereich Admin konfigurieren muss. Der Parameter params Ihrer Aktionsdatei muss Folgendes enthalten:
  params = [{
    description: "A description of the param.",
    label: "A label for the param.",
    name: "action_param_name",
    user_attribute_name: "user_attribute_name",
    required: true,
    sensitive: true,
  }]

Dabei ist user_attribute_name das Nutzerattribut, das auf der Seite Benutzerattribute im Abschnitt Benutzer des Admin-Bereichs im Feld Name definiert ist. required: true bedeutet, dass ein Nutzer einen Wert ungleich null und ein gültiger Wert für dieses Nutzerattribut haben muss, um die Aktion bei der Datenübermittlung zu sehen. sensitive: true bedeutet, dass das Nutzerattribut verschlüsselt ist und nie in der Looker-Benutzeroberfläche angezeigt wird, sobald es eingegeben wurde. Sie können mehrere Nutzerattribut-Unterparameter angeben.

  1. Stellen Sie die Updates auf dem Action Hub-Server bereit.
    • Wenn Sie eine neue Aktion hinzufügen, muss ein Looker-Administrator die Aktion aktivieren. Dazu muss er im Bereich Admin auf der Seite Aktionen neben der Aktion auf die Schaltfläche Aktivieren klicken.
    • Wenn Sie eine vorhandene Aktion aktualisieren, aktualisieren Sie die Liste der Aktionen, indem Sie auf die Schaltfläche Aktualisieren klicken. Klicken Sie dann auf die Schaltfläche Einstellungen.
  2. Auf der Seite für die Aktionseinstellungen/-aktivierung muss ein Looker-Administrator die Formularfelder der Aktion so konfigurieren, dass Informationen aus dem Nutzerattribut abgerufen werden. Dazu klickt er rechts neben dem entsprechenden Feld auf das Nutzerattributsymbol und wählt das gewünschte Nutzerattribut aus.

requiredField-Parameter in Aktionen auf Zellenebene

Bei Aktionen auf Zellenebene können Sie die LookML-Felder Ihres Modells so konfigurieren, dass Daten an dieses Aktionsziel gesendet werden. Dazu geben Sie im Parameter requiredFields Ihrer Aktionsdatei an, welche Tags von Ihrer Aktion unterstützt werden.

Parameter Erforderlich Beschreibung Datentyp
tag Nein Falls vorhanden, entspricht dies einem Feld mit diesem Tag. String
any_tag Nein Falls vorhanden, wird tag ersetzt und stimmt mit einem Feld überein, das eines der angegebenen Tags enthält. String
all_tags Nein Falls vorhanden, wird tag ersetzt und stimmt mit einem Feld überein, das alle angegebenen Tags enthält. String

Unterstützte Datenformate

Die Klasse DataActionRequest definiert, welches Datenübermittlungsformat für die Aktion verfügbar ist. Für Aktionen auf Abfrageebene enthält die Anfrage einen Anhang, der in verschiedenen Formaten vorliegen kann. Für die Aktion können entweder ein oder mehrere supportedFormats angegeben werden oder der Nutzer kann das Format auswählen, indem alle möglichen Formate angegeben werden. Bei Aktionen auf Zellenebene ist der Wert der Zelle ab DataActionRequest vorhanden.

Aktion für OAuth konfigurieren

Sie können Ihre Aktion so konfigurieren, dass sich Nutzer mit OAuth für die Aktion authentifizieren können. Auch wenn der Looker Action Hub zustandslos bleiben muss, können Sie einen Status über eine Formularanfrage von der Looker Action API erzwingen.

OAuth-Ablauf für Looker-Aktion

Für Aktionen im Looker Action Hub können Sie ein OAuthAction anstelle eines Hub.Action erweitern, um einen booleschen Wert festzulegen, der angibt, welche OAuth-Methoden zum Authentifizieren eines Nutzers in einer Aktion erforderlich sind. Für jede OAuth- oder statusaktivierte Aktion speichert Looker einen Nutzer- und einen Aktionsstatus, sodass jede Kombination aus Aktion und Nutzer ein unabhängiges OAuth-Ereignis hat.

Der Ablauf zum Erstellen von Aktionen umfasst in der Regel eine /form-Anfrage gefolgt von einer /execute-Anfrage. Für OAuth sollte die /form-Anfrage eine Methode enthalten, um festzustellen, ob der Nutzer beim Zieldienst authentifiziert ist. Wenn der Nutzer bereits authentifiziert ist, sollte die Aktion ein normales /form-Objekt in Übereinstimmung mit der /execute-Anfrage zurückgeben. Wenn der Nutzer nicht authentifiziert ist, gibt die Aktion einen Link zurück, der einen OAuth-Ablauf initialisiert.

Status wird mit der OAuth-URL gespeichert

Looker sendet eine HTTP-POST-Anfrage mit leerem Text an den ActionList-Endpunkt. Wenn die Aktion in ihrer Definition uses_oauth: true zurückgibt, wird in jeder /form-Anfrage von Looker ein einmaliges state_url gesendet. Die state_url ist eine spezielle URL zur einmaligen Verwendung, mit der der Status eines Nutzers für eine bestimmte Aktion festgelegt wird.

Wenn der Nutzer nicht beim Endpunkt authentifiziert ist, sollte das zurückgegebene /form eine form_field vom Typ oauth_link enthalten, die zum Endpunkt /oauth einer Aktion führt. state_url sollte verschlüsselt und als state-Parameter im zurückgegebenen oauth_url gespeichert werden. Beispiel:

{
        "name": "login",
        "type": "oauth_link",
        "label": "Log in",
        "description": "OAuth Link",
        "oauth_url": "ACTIONHUB_URL/actions/my_action/oauth?state=encrypted_state_url"
}

In diesem Beispiel leitet der Endpunkt /oauth den Nutzer zum Authentifizierungsserver weiter. Der Endpunkt /oauth erstellt die Weiterleitung in der Methode oauthUrl(...) in einer OAuth-Aktion, wie in der Dropbox-OauthUrl dargestellt.

Der Parameter state, der diesen verschlüsselten state_url enthält, sollte an den Looker Action Hub übergeben werden.

Status wird mit dem Weiterleitungs-URI des Action Hub gespeichert

Am /oauth-Endpunkt wird auch ein redirect_uri für den Action Hub erstellt und an die oauthUrl(...)-Methode der Aktion übergeben. Diese redirect_uri hat das Format /actions/src/actions/my_maction/oauth_redirect und ist der Endpunkt, der verwendet wird, wenn die Authentifizierung ein Ergebnis zurückgibt.

Dieser Endpunkt ruft die Methode oauthFetchInfo(...) auf, die von der Methode OauthAction implementiert werden sollte, um die erforderlichen Informationen zu extrahieren und zu versuchen, vom Authentifizierungsserver empfangene Status oder auth zu empfangen oder zu speichern.

Der state entschlüsselt das verschlüsselte state_url und verwendet es, um state zurück an Looker zu senden. Wenn ein Nutzer das nächste Mal eine Anfrage an diese Aktion stellt, wird der neu gespeicherte Status an den Looker Action Hub gesendet.

Aktionsdateien zum Looker Action Hub-Repository hinzufügen

Sobald Ihre Aktionsdatei geschrieben ist, führen Sie im Looker Action Hub-Repository folgende Schritte aus:

  1. Fügen Sie die Aktionsdatei (z. B. my_action.ts) zu actions/src/actions/index.ts hinzu.

    import "./my_action/my_action.ts"

  2. Fügen Sie alle Node.js-Paketanforderungen hinzu, die Sie beim Schreiben Ihrer Aktion verwendet haben. Beispiel:

    yarn add aws-sdk
yarn add express

  3. Installieren Sie die Node.js-Abhängigkeiten des Looker Action Hub-Servers.

    yarn install

  4. Führe alle von dir geschriebenen Tests durch.

yarn test

Aktion testen

Für einen vollständigen Test können Sie Ihre Aktion für Ihre Looker-Instanz durchführen, indem Sie einen Private Action Hub-Server hosten. Dieser Server muss sich im öffentlichen Internet mit einem gültigen SSL-Zertifikat befinden und Verbindungen oder HTTPS-Anfragen zu und von Looker initiieren und empfangen können. Dazu können Sie eine cloudbasierte Plattform wie Heroku verwenden, wie im folgenden Beispiel gezeigt. Alternativ können Sie eine beliebige Plattform verwenden, die die oben genannten Anforderungen erfüllt.

Lokalen Action Hub-Server einrichten

In diesem Beispiel führen wir die Aktion aus, die wir im GitHub-Repository looker-open-source/actions/src/actions entwickelt haben, und übergeben den Code per Commit an einen neuen Git-Zweig. Wir empfehlen, mit Zweigen an Features zu arbeiten, damit Sie Ihren Code problemlos verfolgen und bei Bedarf ganz einfach eine PR mit Looker erstellen können.

  1. Erstellen Sie zuerst Ihren Zweig und führen Sie dann das Staging und Commit Ihrer Arbeit durch. Beispiel:

    git checkout -b my-branch-name
git add file-names
git commit -m commit-message

  2. Um in diesem Beispiel einen Zweig an Heroku zu übertragen, konfigurieren Sie Ihr Git-Repository mit Heroku als Remote-Option in der Befehlszeile:

    heroku login
heroku create
git push heroku

  3. Heroku gibt die öffentliche URL zurück, auf der jetzt der Action Hub gehostet wird. Rufen Sie die URL auf oder führen Sie heroku logs aus, um zu prüfen, ob der Action Hub ausgeführt wird. Wenn Sie die öffentliche URL vergessen haben, können Sie Folgendes in der Befehlszeile ausführen:

    heroku info -s | grep web_url

    Heroku gibt Ihre öffentliche URL zurück. Beispiel: https://my-heroku-action-server-1234.herokuapp.com

  4. Legen Sie in der Befehlszeile die Action Hub-Basis-URL fest:

    heroku config:set ACTION_HUB_BASE_URL="https://my-heroku-action-server-1234.herokuapp.com"

  5. Legen Sie Ihr Action Hub-Label fest:

    heroku config:set ACTION_HUB_LABEL="Your Action Hub"

  6. Looker verwendet ein Autorisierungstoken, um eine Verbindung zum Action Hub herzustellen. Generieren Sie das Token in der Befehlszeile:

    heroku run yarn generate-api-key

    Wenn Sie Heroku nicht verwenden, wie in diesem Beispiel, verwenden Sie stattdessen:

    yarn generate-api-key

    Heroku gibt Ihr Autorisierungstoken zurück. Beispiel: Authorization: Token token="abcdefg123456789"

  7. Legen Sie Ihr Action Hub-Secret mit dem geheimen Schlüssel fest:

    heroku config:set ACTION_HUB_SECRET="abcdefg123456789"

    Für vom Kunden gehostete Bereitstellungen müssen möglicherweise zusätzliche Umgebungsvariablen konfiguriert werden, die hier nicht dokumentiert sind.

  8. Fügen Sie die Aktion in Ihrer lokalen Looker-Instanz ein. Klicken Sie dazu auf Admin > Aktionen.

    • Klicken Sie unten in der Liste der Aktionen auf Add Action Hub (Aktions-Hub hinzufügen).
    • Geben Sie die Action Hub URL und optional einen Geheimschlüssel ein.
    • Suchen Sie im Looker-Menü Admin in der Liste Aktionen nach Ihrer Aktion.
    • Klicken Sie auf Aktivieren.

Wenn bestimmte Arten von Daten von Looker übergeben werden müssen, müssen Sie alle Modelle so konfigurieren, dass sie den entsprechenden tags-Parameter enthalten.

Jetzt können Sie Ihre Aktion testen.

Aktionen auf Dashboard- und Abfrageebene testen

Konfigurieren Sie das LookML-Modell in Ihrer Looker-Instanz bei Bedarf mit Tags. Erstellen und speichern Sie einen Look. Klicken Sie im gespeicherten Look auf das Menü rechts oben und wählen Sie Senden mit der Aktion als Ziel aus. Wenn Sie ein Formular für die Übermittlung haben, rendert Looker es im Fenster Gesendet.

Klicken Sie auf Test senden, um die Daten zu übermitteln. Der Status der Aktion wird im Scheduler-Verlauf im Bereich Admin angezeigt. Wenn bei der Aktion ein Fehler auftritt, wird dieser im Admin-Bereich angezeigt. Looker sendet dann eine E-Mail mit der Fehlermeldung an den Nutzer, der die Aktion gesendet hat.

Aktionen auf Zellenebene testen

Richten Sie ein LookML-Feld mit den richtigen Tags für Ihre Aktion ein. Führen Sie in der Looker-Instanz eine Abfrage aus, die dieses Feld enthält. Suchen Sie das Feld in der Datentabelle. Klicken Sie in der Zelle auf … und wählen Sie im Drop-down-Menü … aus. Falls Fehler auftreten, müssen Sie die Datentabelle vollständig aktualisieren, nachdem Sie diese Fehler behoben haben.

Benutzerdefinierte Aktion veröffentlichen und aktivieren

Es gibt zwei Publikationsoptionen für benutzerdefinierte Aktionen:

Nach der Veröffentlichung Ihrer Aktion können Sie sie im Bereich Verwaltung auf der Seite Aktionen aktivieren.

Im Looker Action Hub veröffentlichen

Dieser Ansatz ist am einfachsten und funktioniert für jede Aktion, die Sie für alle Nutzer von Looker verfügbar machen möchten.

Nachdem deine Aktion getestet wurde, kannst du eine PR an das looker-open-source/actions-Repository in GitHub senden.

  1. Geben Sie den folgenden Befehl ein:

    git push <your fork> <your development branch>

  2. Erstellen Sie die Pull-Anfrage mit dem Repository looker-open-source/actions als Ziel.

  3. Füllen Sie das Einreichungsformular für den Looker Marketplace und Action Hub aus. Weitere Informationen zu den Formularanforderungen finden Sie unter Inhalte beim Looker Marketplace einreichen.

    Looker prüft Ihren Aktionscode. Wir behalten uns das Recht vor, Ihre PR abzulehnen, können Ihnen aber bei Problemen helfen und Verbesserungsvorschläge machen. Anschließend führen wir den Code im Repository looker-open-source/actions zusammen und stellen ihn in actions.looker.com bereit. Sobald der Code bereitgestellt wurde, steht er allen Looker-Kunden zur Verfügung.

  4. Aktivieren Sie die Aktion in Ihrer Looker-Instanz, damit sie als Option für die Datenübermittlung angezeigt wird.

Auf einem Private Action Hub-Server veröffentlichen

Wenn Sie benutzerdefinierte Aktionen haben, die auf Ihr Unternehmen oder Ihren Anwendungsfall beschränkt sind, sollten Sie sie nicht dem Repository looker-open-source/actions hinzufügen. Erstellen Sie stattdessen einen privaten Action Hub mit demselben Node.js-Framework, mit dem Sie Ihre Aktion testen.

Sie können Ihren internen Action Hub-Server in Ihrer eigenen Infrastruktur oder mit einer cloudbasierten Anwendungsplattform einrichten (in unserem Beispiel Heroku verwendet). Vergessen Sie nicht, den Looker Action Hub vor der Bereitstellung mit Ihrem Private Action Hub-Server abzuzweigen.

LookML-Modell zur Verwendung mit einer Aktion konfigurieren

Sowohl für benutzerdefinierte Aktionen als auch für Aktionen, die im Looker Action Hub verfügbar sind, müssen Sie die relevanten Datenfelder mithilfe des Parameters tags in Ihrem LookML-Modell identifizieren. Die Seite Aktionen im Admin-Bereich enthält Informationen zu den Tags, die gegebenenfalls für den Dienst erforderlich sind.

Bei einer Twilio Send Message-Integration wird beispielsweise eine Nachricht an eine Liste von Telefonnummern gesendet. Auf der Seite Aktionen im Bereich Admin wird für die Integration der Subtext „Aktion kann mit Abfragen verwendet werden, deren Feld phone gekennzeichnet ist“ angezeigt.

Das bedeutet, dass der Dienst Twilio Send Message eine Anfrage benötigt, die ein Telefonnummernfeld enthält und mithilfe des Parameters tags ermittelt, welches Feld in der Anfrage Telefonnummern enthält. Sie identifizieren ein Telefonnummernfeld in LookML, indem Sie tags: ["phone"] für dieses Feld angeben. Ihr LookML-Code für ein Telefonnummernfeld könnte beispielsweise folgendermaßen aussehen:

dimension: phone {
  tags: ["phone"]
  type: string
  sql: ${TABLE}.phone ;;
}

Bei einer Integration, für die keine Tags erforderlich sind, wird im Bereich Admin auf der Seite Aktionen der Subtext „Aktion kann mit jeder Abfrage verwendet werden“ angezeigt.

Achten Sie darauf, alle Pflichtfelder in Ihrem LookML-Modell mit dem Parameter tags festzulegen, damit Ihre Nutzer den Dienst zum Senden von Daten verwenden können.

Nächste Schritte

Informationen zum Bereitstellen der Inhalte eines Looks oder Explores oder eines Dashboards an einen integrierten Dienst