Daten über einen Aktions-Hub freigeben

Neben der Bereitstellung von Inhalten in den integrierten Zielen von Looker können Sie Aktionen – auch Integrationen genannt – verwenden, um Inhalte über einen Action Hub-Server an Looker zu übergeben.

Aktionen, die über einen Action Hub-Server erfolgen, unterscheiden sich von Datenaktionen, die durch den LookML-Parameter action definiert sind.

Auf dieser Seite werden die Optionen zur Erstellung benutzerdefinierter Aktionen beschrieben, die Sie zum Looker Action Hub hinzufügen oder zu Ihrem eigenen Hub für private Aktionen hinzufügen können. Außerdem wird auf dieser Seite beschrieben, wie Sie einen lokalen Aktions-Hub-Server einrichten, um Ihre benutzerdefinierten Aktionen zu testen oder einen privaten Aktions-Hub-Server auszuführen.

Wenn Sie Aktionen verwenden möchten, haben Sie folgende Möglichkeiten:

Nachdem die Aktion zum Aktions-Hub hinzugefügt wurde, kann sie von einem Looker-Administrator aktiviert werden, um Looker-Inhalte an diese Dienste zu senden.

Sie können auch mehrere Aktions-Hubs einrichten, wenn Sie die Einbindung von Looker über den Looker Action Hub verwenden und auch Ihre eigenen privaten oder benutzerdefinierten Aktionen hosten möchten. Die Aktionen für jeden Aktions-Hub werden auf der Seite Aktionen des Steuerfelds Verwaltung angezeigt.

Der Looker Action Hub

Looker hostet und bietet den Looker Action Hub, einen zustandslosen Server, der die Looker's Action API implementiert und beliebte Aktionen bereitstellt. Alle Daten, die Ihre Nutzer über eine Aktion senden, werden vorübergehend auf dem Looker Action Hub-Server und nicht auf der Looker-Instanz verarbeitet.

Looker ist bereits in mehreren Diensten integriert. Auf der Seite Administratoreinstellungen – Aktionen erfahren Sie, wie Sie diese Dienste aktivieren.

Anforderungen für Looker Action Hub

Damit Sie Looker-Integrationen verwenden können, muss der Looker Action Hub mit der Looker-Instanz kommunizieren und diese Anforderungen erfüllen können. Administratoren von kundenseitig gehosteten Instanzen müssen möglicherweise zusätzliche Faktoren berücksichtigen, wenn sie Looker-Integrationen von Looker Action Hub aktivieren, insbesondere Integrationen, die gestreamte Ergebnisse unterstützen oder OAuth verwenden.

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

Wenn Ihre Looker-Bereitstellung diesen Anfragen nicht gerecht wird oder die Funktion IP-Zulassungsliste auf Ihrer Looker-Instanz aktiviert ist, können Sie einen lokalen Aktions-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 Streamingaktionen 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 in der Lage sein, diese Endpunkte zu erreichen:

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-Nutzers an das Looker Action Hub-Netzwerk

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

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 für Aktionen, die gestreamte Ergebnisse unterstützen oder OAuth verwenden, Anfragen an die Looker-Instanz senden.

Mit einer Streaming-Aktion können Abfragen verarbeitet werden, die alle Ergebnisse liefern. Für OAuth-aktivierte Aktionen wird die Authentifizierung des Nutzers ü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 und keine nutzerspezifischen Anmeldedaten jeglicher Art speichert.

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, <host_looker_url> in eine IP-Adresse aufzulösen und Anfragen an das Netzwerk zu senden, in dem sich die 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 nutzen zu können, die gestreamte Ergebnisse unterstützen oder OAuth nutzen.

Überlegungen zu vom Kunden gehosteten Instanzen

Damit Sie Looker-Integrationen verwenden können, muss der Looker Action Hub mit der Looker-Instanz kommunizieren und diese Anforderungen erfüllen können. Dies ist aus vom Kunden gehosteten Looker-Instanzen 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 von Looker Action Hub kommen, z. B. zu hängenden Abfragen oder nicht verfügbaren Aktionen.

Looker-Administratoren können eine der unten aufgeführten Lösungen implementieren, um das potenzielle Problem zu beheben, dass Looker Action Hub nicht mit der Looker-Instanz kommunizieren kann. 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, d. h., der Looker Action Hub kann keine Anfragen von der Looker-Instanz empfangen, können sich Looker-Administratoren an den Looker-Account Manager wenden, um die public_host_url-Lizenzfunktion zu aktivieren. Dieses Lizenzfeature zeigt die --public-host-url-Startoption an, 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 Callback-URLs von Looker Action Hub und leitet diese Callback-URLs über einen Reverse-Proxy weiter, der public_host_url als öffentlich auflösbaren Namen verwendet. Dieser Reverse-Proxy akzeptiert nur Anfragen von den statischen ausgehenden IP-Adressen für den Looker Action Hub. Looker-Administratoren, die diese Methode verwenden, müssen der IP-Adresse des ausgehenden Traffics von der Looker Action Hub, von der die Looker Action Hub Anfragen sendet, zur Zulassungsliste hinzugefügt werden: 35.153.89.114, 104.196.138.163 und 35.169.42.87.

  • Wenn die vom Kunden gehostete Instanz-URL von der Looker-Instanz aufgelöst werden kann, aber der Looker Action Hub 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. Zur Lösung dieses Problems müssen Looker-Administratoren die ausgehenden IP-Adressen, von denen der Looker Action Hub Anfragen an die Looker-Instanz sendet, der Zulassungsliste hinzugefügt werden: 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 Aktions-Hub für alle Aktionen oder nur für Aktionen bereitstellen, die gestreamte Ergebnisse unterstützen oder OAuth verwenden.

  • Um einen vom Kunden gehosteten Aktions-Hub bereitzustellen, muss die JAR-Datei auf einem öffentlichen Server gehostet werden, damit der Looker Action Hub mit ihm kommunizieren kann. Looker empfiehlt diese Lösung jedoch nicht.

Ein weiterer Grund, warum die OAuth- und Streamingaktionen auf einer vom Kunden gehosteten Looker-Instanz möglicherweise nicht verwendet werden können, ist, wenn die Instanz ein SSL-Zertifikat verwendet, das von einer Zertifizierungsstelle ausgestellt wurde, die nicht in dieser Liste aufgeführt 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. Beispiele für funktionale Codes finden Sie 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. Veröffentlichung und Aktivierung Ihrer Aktion, entweder im Looker Action Hub oder auf Ihrem eigenen Hub für private Aktionen

Wie bei jeder Aktion müssen Sie möglicherweise Ihre LookML-Modelle mit bestimmten Parametern konfigurieren, bevor Sie Ihre Daten mit der Aktion übermitteln können.

Entwicklungs-Repository einrichten

Der Looker Action Hub ist ein Node.js-Server, der in TypeScript geschrieben wurde. Er ist eine kleine Ebene über modernem JavaScript, die Typinformationen hinzufügt, um Programmierfehler zu erkennen. Wenn Sie mit JavaScript vertraut sind, sollten Sie die meisten TypeScript-Sprachen kennen.

Für die Ausführung des Looker Action Hub ist die folgende Software erforderlich:

  • Node.js
  • Knotenversionsmanager (NVM zur Auswahl der richtigen Node.js-Version)
  • Yarn (zum Verwalten von Abhängigkeiten)

Nachdem Sie die erforderliche Software installiert haben, können Sie Ihre Entwicklungsumgebung einrichten. Im folgenden Beispiel wird Git verwendet.

  1. Klonen Sie das Repository looker-open-source/actions 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. Füllen Sie das Verzeichnis mit den Dateien, die Sie für die Aktion benötigen. Ein Beispiel für eine Dateistruktur finden Sie im GitHub-Repository zu Aktionen.

Looker empfiehlt Folgendes:

  • Eine Readme-Datei, in der der Zweck und die Authentifizierung deiner Aktion erläutert wird
  • PNG-Symbol, das im Looker Action Hub (oder dem Hub für private Aktionen auf Ihrer Looker-Instanz) und in den Looker-Datenübermittlungsfenstern angezeigt wird
  • Alle Dateien für Tests, die Sie mit Ihrem Aktionscode ausführen möchten – das 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 in dem Dienst gespeichert werden. Alle Informationen, die zur Ausführung der Aktion erforderlich sind, müssen in den Anfrageaufrufen der Aktionsdatei angegeben werden.

Der genaue Inhalt der Aktionsdatei variiert je nach Dienst, Typ oder Ebene, auf der die Aktion ausgeführt wird, und 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. Looker API-Anfragen werden jedes Mal an 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. Es gibt auch eine /form-Methode, mit der zusätzliche Informationen vom Nutzer erfasst werden können, bevor die Aktion ausgeführt wird. Die Felder, die Sie in /form angeben, erscheinen im Pop-up-Fenster Senden oder Planen, wenn Nutzer die Aktion als Ziel für die Datenübermittlung auswählen.

Wenn Sie die Looker Action API verwenden, kann das Format dieser Parameter anders aussehen.

Geben Sie in die Aktionsdatei mindestens die folgenden Parameter an, die mit Required (Erforderlich) gekennzeichnet sind:

Parameter Erforderlich Beschreibung Datentyp
name Ja Ein eindeutiger Name für die Aktion. Dies sollte für alle Aktionen im Looker Action Hub eindeutig sein. String
url Ja Eine absolute URL des /execute-Endpunkts für diese Aktion. String
label Ja Ein menschenlesbares Label für die Aktion. String
supportedActionTypes Ja Eine Liste der von der Aktion unterstützten Aktionstypen. Gültige Werte sind "cell", "query" und "dashboard". String
formURL Nein Eine absolute URL des /form-Endpunkts für diese Aktion. String
description Nein Beschreibung der Aktion. String
params Nein Array von parameters für die Aktion. Geben Sie für jeden Parameter den Namen, das Label und die Beschreibung im Stringformat an. Das sind die Felder, die auf der Seite zum Aktivieren der Aktion im Steuerfeld Admin angezeigt werden. Wenn Sie festlegen möchten, wie Nutzer Daten für ein Aktionsziel bereitstellen können, haben Sie die Möglichkeit, ein Nutzerattribut festzulegen, für das ein bestimmter Wert festgelegt sein 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 Formatierungsoptionen, die für die Aktion unterstützt werden. Gültige Werte sind "formatted" und "unformatted". String
supportedVisualizationFormattings Nein Eine Liste mit Visualisierungsformatierungsoptionen, die von der Aktion unterstützt werden. 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 der Pflichtfelder, mit denen diese Aktion kompatibel ist. Wenn die Liste mehrere Einträge enthält, sind für die Aktion mehrere Felder erforderlich. RequiredField
supportedDownloadSettings Nein Ein boolescher Wert, der bestimmt, ob an die Aktion eine einmalige Download-URL gesendet wird, um das unbegrenzte Streaming von Daten zu ermöglichen. Der Parameter wird durch den Parameter usesStreaming festgelegt, der ein boolescher Wert für true/false ist. Wenn usesStreaming = true, dann supportedDownloadSettings = url. Wenn usesStreaming = false, dann supportedDownloadSettings = push. Boolesch
usesOAuth Nein Ein boolescher Wert, der bestimmt, ob die Aktion eine OAuth-Aktion ist. Hiermit wird festgelegt, ob für die Aktion ein einmaliger Link an state gesendet wird, mit dem sich die Aktion für einen bestimmten Nutzer festlegen lässt. Boolesch
usesStreaming Nein Ein boolescher Wert, der bestimmt, ob die Aktion gestreamte Abfrageergebnisse unterstützt. Klicken Sie in der Liste der integrierten Dienste auf das Kästchen Ergebnisse können mit „Ja“/„Nein“ gestreamt werden. Für Aktionen, die Ergebnisse streamen, ist möglicherweise die Konfiguration eines lokalen Aktions-Hub-Servers erforderlich. Weitere Informationen finden Sie auf der Seite Lokalen Aktions-Hub für Aktionen einrichten, die OAuth oder Streaming verwenden. Boolesch
minimumSupportedVersion Nein Die Looker-Mindestversion, in der die Aktion in der Aktions-Hub-Liste unter Verwaltung angezeigt wird. String

Beispiele für Looker Action Hub-Aktionen finden Sie auf GitHub.

Unterstützte Aktionstypen

Looker unterstützt drei Arten von Aktionen, die im Parameter supportedActionTypes Ihrer Aktion angegeben sind: Abfrage, Zelle und Dashboard.

  • Aktion auf Suchanfragenebene:Eine Aktion, die eine gesamte Abfrage sendet. Die Segmentaktion ist beispielsweise eine Aktion auf Abfrageebene.
  • Aktion auf Zellenebene:Mit einer Aktion auf Zellenebene wird der Wert einer einzelnen Zelle in einer Datentabelle gesendet. Dieser Aktionstyp unterscheidet sich von Datenaktionen, die für Dimensionen oder Messwerte mit dem Parameter action definiert werden können. Um Informationen aus einer bestimmten Zelle in einer Tabelle zu senden, verwendet Looker Tags, um Aktionen den entsprechenden Zellen zuzuordnen. Die Aktionen müssen angeben, welche Tags sie in requiredFields unterstützen. Für die Zuordnung von Aktionen und Feldern müssen Felder in LookML mit dem LookML-tags-Parameter angeben, welchen Tags sie zugeordnet sind. Die Twilio Message action verwendet beispielsweise ein phone-Tag, damit LookML-Entwickler steuern können, welche Telefonnummernfelder die Twilio-Aktion enthält.
  • Eine Aktion auf Dashboardebene:Eine Aktion auf Dashboardebene unterstützt das Senden eines Bildes eines Dashboards. Zum Beispiel sendet die SendGrid-Aktion Dashboard-Bilder per E-Mail.

Nutzerattribute zu benutzerdefinierten Aktionen hinzufügen

Bei benutzerdefinierten Aktionen können Sie im Parameter params der Aktionsdatei Nutzerattribute hinzufügen. Wenn der Parameter erforderlich ist, muss jeder Nutzer zusätzlich zu der Berechtigung send_to_integration einen Wert für dieses Attribut in seinem Nutzerkonto oder in einer Nutzergruppe haben, der er zugeordnet ist, um die Aktion als Zieloption beim Senden oder Planen von Inhalten zu sehen.

So fügen Sie Ihrer Aktion ein Nutzerattribut hinzu:

  1. Ein Looker-Administrator muss möglicherweise das Nutzerattribut erstellen, das user_attribute_param entspricht, falls noch nicht vorhanden.
  2. Legen Sie einen gültigen Wert für das Nutzerattribut für die Nutzer oder Nutzergruppen fest, die Inhalte an Ihr Aktionsziel liefern müssen. Diese Nutzer benötigen außerdem die Berechtigung send_to_integration.
  3. Der Parameter params steht für die Formularfelder, die ein Looker-Administrator auf der Seite zum Aktivieren der Aktion in der Liste Aktionen im Bereich Admin konfigurieren muss. Geben Sie im Parameter params der Aktionsdatei Folgendes an:
  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 im Feld Name auf der Seite User Attributes im Abschnitt Users des Admin-Steuerfelds definiert ist. required: true bedeutet, dass ein Nutzer für dieses Nutzerattribut einen ungleich null und gültigen Wert definiert haben muss, damit die Aktion beim Senden von Daten angezeigt wird. sensitive: true bedeutet, dass das Nutzerattribut verschlüsselt ist und nach der Eingabe nicht in der Looker-UI angezeigt wird. Sie können mehrere Nutzerattribut-Unterparameter angeben.

  1. Stellen Sie Ihre Updates auf dem Action Hub-Server bereit.
    • Wenn Sie eine neue Aktion hinzufügen, muss ein Looker-Administrator die Aktion aktivieren. Dazu klickt er auf der Seite Aktionen im Bereich Admin neben der Aktion auf die Schaltfläche Aktivieren.
    • Wenn Sie eine vorhandene Aktion aktualisieren möchten, aktualisieren Sie die Liste der Aktionen durch Klicken auf die Schaltfläche Aktualisieren. Klicken Sie dann auf die Schaltfläche Einstellungen.
  2. Auf der Seite „Aktionseinstellungen“ 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

Für Aktionen auf Zellenebene können Sie die LookML-Felder Ihres Modells konfigurieren, um Daten an dieses Aktionsziel zu übergeben. Geben Sie dazu im Parameter requiredFields Ihrer Aktionsdatei an, welche Tags Ihre Aktion unterstützt.

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

Unterstützte Datenformate

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

Aktion für OAuth konfigurieren

OAuth-fähige Aktionen können nicht über den Looker Action Hub für Looker-Instanzen konfiguriert werden, bei denen die Funktion IP-Zulassungsliste aktiviert ist oder die die Anforderungen von Looker Action Hub nicht erfüllen können. Weitere Informationen zum Konfigurieren einer Aktion für OAuth finden Sie auf der Seite Lokalen Aktions-Hub für Aktionen einrichten, die OAuth oder Streaming verwenden.

Sie können Ihre Aktion so konfigurieren, dass sich Nutzer mit OAuth 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-Vorgang für Looker-Aktion

Für Aktionen im Looker Action Hub können Sie anstelle von Hub.Action einen OAuthAction erweitern, um einen booleschen Wert festzulegen, der angibt, welche OAuth-Methoden erforderlich sind, um einen Nutzer in einer Aktion zu authentifizieren. Für jede OAuth-fähige oder zustandsaktivierte Aktion speichert Looker einen nutzerspezifischen Status pro Aktion, sodass jede Aktion und jede Nutzerkombination ein unabhängiges OAuth-Ereignis hat.

Der Ablauf zum Erstellen von Aktionen umfasst in der Regel eine /form-Anfrage gefolgt von einer /execute-Anfrage. Bei OAuth sollte die Anfrage /form eine Methode enthalten, um festzustellen, ob der Nutzer innerhalb des Zieldienstes authentifiziert ist. Wenn der Nutzer bereits authentifiziert ist, sollte die Aktion gemäß den Anforderungen von /execute eine normale /form zurückgeben. Ist der Nutzer nicht authentifiziert, gibt die Aktion einen Link zurück, mit dem ein OAuth-Vorgang initialisiert wird.

Status mit der OAuth-URL speichern

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 eine einmalige Verwendung an state_url gesendet. state_url ist eine spezielle Einmal-URL, die den Status eines Nutzers für eine bestimmte Aktion festlegt.

Wenn der Nutzer nicht mit dem Endpunkt authentifiziert ist, sollte die zurückgegebene /form einen form_field vom Typ oauth_link enthalten, der zum /oauth-Endpunkt einer Aktion geht. 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(...) für eine OAuth-Aktion, wie in der Dropbox OauthUrl gezeigt.

Der Parameter state mit dieser verschlüsselten state_url sollte an den Looker Action Hub übergeben werden.

Status mit dem Aktions-Hub-Weiterleitungs-URI wird gespeichert

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

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

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

Aktionsdateien dem Looker Action Hub-Repository hinzufügen

Sobald die Aktionsdatei erstellt wurde, führen Sie im Looker Action Hub-Repository Folgendes 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. Node.js-Abhängigkeiten des Looker Action Hub-Servers installieren

    yarn install

  4. Führen Sie alle von Ihnen geschriebenen Tests aus.

yarn test

Aktion testen

Sie können Ihre Aktion an der Looker-Instanz durchführen, indem Sie einen privaten Action Hub-Server hosten. Dieser Server muss im öffentlichen Internet mit einem gültigen SSL-Zertifikat sein und Verbindungen oder HTTPS-Anfragen zu und von Looker initiieren und empfangen können. Dazu können Sie eine cloudbasierte Plattform wie Heroku wie im folgenden Beispiel verwenden oder 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 erstellt haben, und übertragen den Code in einen neuen Git-Zweig. Wir empfehlen, Funktionen mit Zweigen zu verwenden, damit Sie Ihren Code einfach verfolgen und bei Bedarf eine PR mit Looker erstellen können.

  1. Erstellen Sie zuerst Ihren Zweig und stellen Sie dann Ihre Arbeit bereit. Beispiel:

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

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

    heroku login
heroku create
git push heroku

  3. Heroku gibt die öffentliche URL zurück, auf der Sie jetzt den Aktions-Hub hosten. Rufen Sie die URL auf oder führen Sie heroku logs aus, um zu prüfen, ob der Aktions-Hub ausgeführt wird. Wenn Sie die öffentliche URL vergessen, 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 Aktions-Hub-Basis-URL fest:

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

  5. Legen Sie das Aktions-Hub-Label fest:

    heroku config:set ACTION_HUB_LABEL="Your Action Hub"

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

    heroku run yarn generate-api-key

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

    yarn generate-api-key

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

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

    heroku config:set ACTION_HUB_SECRET="abcdefg123456789"

    Vom Kunden gehostete Bereitstellungen erfordern möglicherweise die Konfiguration zusätzlicher Umgebungsvariablen, die hier nicht dokumentiert sind.

  8. Fügen Sie die Aktion der lokalen Looker-Instanz hinzu. Rufen Sie dazu Admin > Aktionen auf.

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

Wenn für Ihre Aktion bestimmte Arten von Daten aus Looker erforderlich sind, konfigurieren Sie alle Modelle so, dass sie den entsprechenden tags-Parameter enthalten.

Sie können jetzt Ihre Aktion testen.

Aktionen auf Dashboard- und Abfrageebene testen

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

Klicken Sie auf Test senden, um die Daten zu senden. Der Status der Aktion wird im Planerverlauf im Bereich Planer angezeigt. Wenn bei Ihrer Aktion ein Fehler auftritt, wird sie im Bereich Admin angezeigt und Looker sendet 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 das Symbol ... und wählen Sie im Drop-down-Menü die Option Senden aus. Wenn Sie Fehler erhalten, müssen Sie die Datentabelle nach der Behebung vollständig aktualisieren.

Benutzerdefinierte Aktion veröffentlichen und aktivieren

Für benutzerdefinierte Aktionen gibt es zwei Veröffentlichungsoptionen:

Nachdem die Aktion veröffentlicht wurde, können Sie sie auf der Seite Aktionen im Steuerfeld Verwaltung aktivieren.

Im Looker Action Hub veröffentlichen

Dieser Ansatz ist am einfachsten und funktioniert für jede Aktion, die Sie Looker zur Verfügung stellen möchten.

Nachdem Ihre Aktion getestet wurde, können Sie 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 eine Pull-Anfrage mit dem looker-open-source/actions-Repository als Ziel.

  3. Füllen Sie das Formular zum Einreichen von Angeboten für 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 allen Problemen helfen und Ihnen Verbesserungsvorschläge machen. Anschließend führen wir den Code in das looker-open-source/actions-Repository ein und stellen ihn in actions.looker.com bereit. Nach der Bereitstellung ist der Code für alle Looker-Kunden verfügbar.

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

Auf einem privaten Aktions-Hub-Server veröffentlichen

Wenn benutzerdefinierte Aktionen privat sind, sollten Sie sie nicht dem Repository looker-open-source/actions hinzufügen. Erstellen Sie stattdessen einen privaten Aktions-Hub mit demselben Node.js-Framework, das Sie zum Testen Ihrer Aktion verwendet haben.

Sie können den internen Action Hub-Server in Ihrer eigenen Infrastruktur oder mit einer cloudbasierten Anwendungsplattform einrichten. Denken Sie daran, vor der Bereitstellung den Looker Action Hub an Ihren privaten Aktions-Hub-Server zu binden.

LookML-Modell für eine Aktion konfigurieren

Sowohl für benutzerdefinierte Aktionen als auch für Aktionen, die über den Looker Action Hub verfügbar sind, müssen Sie die relevanten Datenfelder mit dem Parameter tags in Ihrem LookML-Modell identifizieren.

Auf der Seite Aktionen im Bereich Verwaltung finden Sie Informationen zu den Tags, die gegebenenfalls für den Dienst erforderlich sind.

Die Integration von Zapier gibt beispielsweise an, dass sie mit jeder Abfrage funktioniert. Sie müssen den Parameter tags nicht in ein Feld des LookML-Modells einfügen.

Der Dienst Twilio Send Message sendet jedoch eine Nachricht an eine Liste von Telefonnummern. Dazu ist eine Abfrage erforderlich, die ein Telefonnummernfeld enthält und mit dem Parameter tags bestimmt, welches Feld in der Abfrage 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 ;;
}

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

Daten mit einer Aktion liefern

Ihre Daten können abhängig von der Ebene, auf der die Aktion ausgeführt wird, auf verschiedene Arten übermittelt werden. Aktionen werden auf Feld-, Abfrage- oder Dashboard-Ebene ausgeführt und können auf einer oder mehreren Ebenen ausgeführt werden. Jede Aktion, die auf der Seite Aktionen im Steuerfeld Admin aufgeführt ist, enthält eine Beschreibung ihrer Verwendung. Sie können:

Zellendaten werden gesendet

Aktionen auf Feldebene werden auf der Seite Aktionen des Steuerfelds Admin durch eine Beschreibung angezeigt, die „Aktion kann mit Feldern verwendet werden“ oder mit Ja in der Spalte Kann von Feldern verwendet werden in der Liste der integrierten Dienste enthalten.

Aktionen auf Feldebene sind so konzipiert, dass sie eine Zelle mit Daten an den angegebenen Dienst liefern. Sie funktionieren ähnlich wie Datenaktionen, mit der Ausnahme, dass sie über die Looker Action API bereitgestellt werden. Statt einen action-LookML-Parameter für eine Dimension oder einen Messwert zu definieren, müssen Sie Ihr LookML-Modell konfigurieren. Dazu verknüpfen Sie die relevanten Felder mit den Informationen aus der Spalte Tags for this Action (Tags für diese Aktion) in der Liste der integrierten Dienste.

Nachdem Sie die Dienst- und Tagging-Felder im LookML-Modell aktiviert haben, können Sie:

  1. Sieh dir die Daten an, die du im Look-, Dashboard- oder Entdecken-Modus liefern möchtest. Wenn der Dienst „Aktion kann mit Abfragen verwendet werden, die ein getaggtes Feld enthalten...“ angibt, muss Ihre Abfrage oder eine der Kacheln des Dashboards ein oder mehrere Felder mit den erforderlichen Tags enthalten.

  2. Das getaggte Feld in jeder Zelle des Designs, der Dashboard-Kachel oder des Bereichs „Erkunden“ enthält eine Drop-down-Liste mit Auslassungspunkten (...). Klicken Sie auf die Ellipse, um die für diesen Link verfügbaren Aktionen aufzurufen.

  3. Klicken Sie im Abschnitt AKTIONEN auf den Dienst, für den Sie Zeilendaten erhalten möchten.

Dashboard- oder Abfragedaten bereitstellen

Aktionen auf Ebene der Abfrage sind auf der Seite Aktionen des Steuerfelds Admin mit der Beschreibung „Aktion kann für Abfragen mit einem getaggten Feld verwendet werden“ gekennzeichnet. Gemäß der Spalte Kann senden oder planen in der Liste der integrierten Dienste können Sie Jede Zeile (in einem Look oder einer Erkundung) liefern. Aktionen auf Abfrageebene sind so konzipiert, dass die gesamten Abfrageergebnisse aus „Erkunden“ oder „Ansehen“ an den angegebenen Dienst gesendet werden.

Aktionen auf Dashboard-Ebene sind auf der Seite Aktionen des Admin-Steuerfelds mit einer Beschreibung gekennzeichnet, die besagt, dass die Aktion für jedes Dashboard verwendet werden kann. Gemäß der Spalte Senden oder Planen in der Liste der integrierten Dienste können Sie ein Dashboard bereitstellen. Aktionen auf Dashboardebene sind so konzipiert, dass ein Dashboard an den angegebenen Dienst gesendet wird.

Aktivieren Sie den Dienst sowie Tag-Felder im LookML-Modell, sofern nötig.

Informationen zum Bereitstellen von „Ansehen & Entdecken“ finden Sie auf der Dokumentationsseite Looks und Entdecken.

Informationen zum Bereitstellen von Dashboards finden Sie auf den Dokumentationsseiten Legacy-Dashboards bereitstellen und Dashboards planen und senden.