Daten über einen Action Hub freigeben

Sie können Inhalte nicht nur an die integrierten Ziele von Looker senden, sondern auch Aktionen (auch Integrationen genannt) verwenden, um Inhalte an Drittanbieterdienste zu senden, die über einen Action Hub-Server in Looker integriert sind.

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

So können Sie Aktionen verwenden:

Sobald die Aktion dem Aktionshub hinzugefügt wurde, kann ein Looker-Administrator die Aktion aktivieren, damit sie zum Senden von Looker-Inhalten an diese Dienste verwendet werden kann.

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

Looker Action Hub

Looker hostet und stellt den Looker Action Hub zur Verfügung, einen statusfreien Server, der die Action API von Looker implementiert und häufig ausgeführte Aktionen anzeigt. Alle Daten, die Ihre Nutzer mithilfe einer Aktion senden, werden vorübergehend auf dem Looker Action Hub-Server anstatt in Ihrer Looker-Instanz verarbeitet.

Looker ist bereits in mehrere Dienste eingebunden. Informationen zum Aktivieren dieser vorhandenen Dienste finden Sie auf der Dokumentationsseite Administratoreinstellungen – Aktionen.

Anforderungen für den Looker Action Hub

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

Wenn Ihre Looker-Bereitstellung diese Anfragen nicht verarbeiten kann oder die Funktion IP-Zulassungsliste für Ihre Looker-Instanz aktiviert ist, sollten Sie einen lokalen Action Hub-Server einrichten, um private Looker-Integrationen oder benutzerdefinierte Aktionen bereitzustellen. Administratoren von selbst 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 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-Nutzers 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 aus dem Looker Action Hub-Netzwerk an die Looker-Instanz

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

Eine Streaming-Aktion ermöglicht es, dass die Aktion Abfragen verarbeitet, die Alle Ergebnisse liefern. Für OAuth-fähige Aktionen wird die Authentifizierung pro Nutzer über OAuth 2.0-Flows verwendet. OAuth-Aktionen müssen Nutzeranmeldedaten in der Looker-Quellinstanz speichern, da der Looker Action Hub zustandslos und mandantenfähig ist und keine nutzerspezifischen Anmeldedaten 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 in der Looker-Instanz generiert, bevor sie an den Looker Action Hub gesendet werden. Aus diesem Grund muss der Looker Action Hub sowohl den <host_looker_url> in eine IP-Adresse auflösen als auch Anfragen an das Netzwerk senden können, in dem sich Ihre Looker-Instanz befindet.

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

Überlegungen zu kundenseitig gehosteten Instanzen

Damit Sie Looker-Integrationen verwenden können, muss der Looker Action Hub mit der Looker-Instanz kommunizieren und die Anforderungen des Looker Action Hub erfüllen. Bei vom Kunden gehosteten Looker-Instanzen ist das aus verschiedenen Gründen nicht immer möglich. Wenn die bidirektionale Kommunikation zwischen dem Looker Action Hub und der Looker-Instanz nicht möglich ist, kann es zu unerwartetem oder unerwünschtem Verhalten des Looker Action Hub kommen, z. B. abgebrochene Abfragen oder nicht verfügbare 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 beschrieben 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, d. h., der Looker Action Hub keine Anfragen von der Looker-Instanz empfangen kann, können Looker-Administratoren einen Google Cloud-Vertriebsspezialisten kontaktieren, um die Lizenzfunktion public_host_url zu aktivieren. Diese Lizenzfunktion macht die --public-host-url-Startoption verfügbar, mit der Administratoren einen auflösbaren <public_host_url>-Hostname angeben können, der sich vom <host_looker_url> der Instanz unterscheidet. Mit public_host_url wird der Hostname für einige bestimmte Looker Action Hub-Callback-URLs überschrieben und diese Callback-URLs werden über einen Reverse-Proxy weitergeleitet, der public_host_url als öffentlich auflösbaren Namen hat. Dieser Reverseproxy akzeptiert Anfragen nur von den statischen Egress-IP-Adressen für den Looker Action Hub. Looker-Administratoren, die diese Methode verwenden, müssen die Egress-IP-Adressen, von denen der Looker Action Hub Anfragen an die Looker-Instanz sendet, zur Allowlist hinzufügen: 35.153.89.114, 104.196.138.163 und 35.169.42.87.

  • Wenn die URL der vom Kunden gehosteten Instanz aufgelöst werden kann, 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 Egress-IP-Adressen, von denen der Looker Action Hub Anfragen an die Looker-Instanz sendet, zur Allowlist hinzufügen: 35.153.89.114, 104.196.138.163 und 35.169.42.87.

  • Wenn keine der oben genannten Lösungen für die Architektur der Looker-Instanz geeignet ist, können Looker-Administratoren einen vom Kunden gehosteten Action Hub für alle Aktionen oder nur für Aktionen bereitstellen, die Streaming-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 sind die OAuth- und Streamingvorgänge möglicherweise nicht auf einer vom Kunden gehosteten Looker-Instanz verfügbar, wenn für die Instanz ein SSL-Zertifikat verwendet wird, das von einer Zertifizierungsstelle ausgestellt wurde, die nicht in dieser Liste der Root-Zertifikate enthalten ist.

Benutzerdefinierte Aktion erstellen

In diesem Abschnitt wird beschrieben, wie Sie eine benutzerdefinierte Aktion mit dem Looker Action Hub-Quellcode schreiben und testen. Funktionale Codebeispiele finden Sie in den vorhandenen Aktionen im looker-open-source/actions-Repository auf GitHub.

Sie können eine benutzerdefinierte Aktion erstellen, indem Sie:

  1. Entwicklungsrepository einrichten
  2. Aktion schreiben
  3. Aktion testen
  4. Veröffentlichen und Aktivieren Ihrer Aktion, entweder im Looker Action Hub oder auf Ihrem eigenen privaten Action Hub-Server

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

Entwicklungsrepository einrichten

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

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

  • Node.js
  • Node Version Manager (NVM) zum Auswählen 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 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. Fügen Sie Ihrem Verzeichnis die Dateien hinzu, die Sie zum Ausführen Ihrer Aktion benötigen. Eine Beispiel-Dateistruktur finden Sie im GitHub-Repository für Aktionen.

Looker empfiehlt, Folgendes hinzuzufügen:

  • Eine README-Datei, in der der Zweck und die Authentifizierungsmethode für Ihre Aktion erläutert werden
  • Ein PNG-Symbol, das im Looker Action Hub (oder im privaten Action Hub in Ihrer Looker-Instanz) und in den Looker-Fenstern für die Datenbereitstellung angezeigt wird
  • Alle Dateien für Tests, die Sie für Ihren 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 ist das Speichern von Informationen in der Aktionsanwendung oder im Dienst nicht zulässig. Alle Informationen, die zum Ausführen der Aktion erforderlich sind, müssen in den Anforderungsaufrufen der Aktionsdatei angegeben werden.

Der genaue Inhalt der Aktionsdatei hängt vom Dienst, vom Typ oder der Ebene ab, auf der die Aktion ausgeführt wird, und davon, welche Daten- oder Visualisierungsformate 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 wird jedes Mal, wenn ein Nutzer die Aktion in Looker ausführt, ein DataActionRequest übergeben. Der DataActionRequest enthält alle Daten und Metadaten, die zum Ausführen der Aktion erforderlich sind. Es ist auch eine /form-Methode verfügbar, mit der zusätzliche Informationen vom Nutzer erfasst werden können, bevor er die Aktion ausführt. Die Felder, die Sie in /form angeben, werden im Pop-up-Fenster Senden oder Planen angezeigt, wenn Nutzer die Aktion als Ziel für die Datenübermittlung auswählen.

Geben Sie in Ihrer Aktionsdatei mindestens die folgenden Parameter an, die in Ihrer Aktionsdefinition mit Erforderlich gekennzeichnet sind:

Parameter Erforderlich Beschreibung Datentyp
name Ja Ein eindeutiger Name für die Aktion. Dieser Wert muss 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 für Menschen lesbares Label für die Aktion. String
supportedActionTypes Ja 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 /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. 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 Formatierungsoptionen, die von der Aktion unterstützt werden. Gültige Werte sind "formatted" und "unformatted". String
supportedVisualizationFormattings Nein Eine Liste der 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 Beschreibungen der erforderlichen Felder, 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 Ein boolescher Wert, der angibt, ob für die Aktion eine einmal verwendbare Download-URL gesendet wird, um unbegrenztes Streaming von Daten zu ermöglichen. Der Parameter wird durch den Parameter usesStreaming festgelegt, der ein true/false-boolescher Wert ist. Bei usesStreaming = true wird supportedDownloadSettings = url zurückgegeben. Bei usesStreaming = false wird supportedDownloadSettings = push zurückgegeben. Boolesch
usesOAuth Nein Ein boolescher Wert, der angibt, ob es sich bei der Aktion um eine OAuth-Aktion handelt. Dadurch wird festgelegt, ob für die Aktion ein Einmal-Link gesendet wird, damit state für einen bestimmten Nutzer festgelegt werden kann. Boolesch
usesStreaming Nein Ein boolescher Wert, der angibt, ob die Aktion gestreamte Abfrageergebnisse unterstützt. Sehen Sie in der Liste der integrierten Dienste in der Spalte Verwendet Datenstreaming (Ja/Nein) nach. 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 Best Practices-Seite Lokalen Action Hub für Aktionen einrichten, die OAuth oder Streaming verwenden. Boolesch
minimumSupportedVersion Nein Die Mindestversion von Looker, in der die Aktion in der Liste „Action Hub“ im Bereich Admin angezeigt wird. String

Beispiele für die Looker Action Hub-Aktionen sind auf GitHub verfügbar.

Unterstützte Aktionstypen

Looker unterstützt drei Arten von Aktionen, die im Parameter supportedActionTypes Ihrer Aktion angegeben werden: „query“, „cell“ und „dashboard“.

  • Aktion auf Abfrageebene:Bei dieser Aktion wird eine gesamte Abfrage gesendet. Die Segmentaktion ist beispielsweise eine Aktion auf Abfrageebene.
  • Aktion auf Zellebene:Bei einer Aktion auf Zellebene wird der Wert einer einzelnen, bestimmten 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. Wenn Informationen aus einer bestimmten Zelle in einer Tabelle gesendet werden sollen, verwendet Looker Tags, um Aktionen den entsprechenden Zellen zuzuordnen. In requiredFields muss für Aktionen angegeben werden, welche Tags sie unterstützen. Damit Aktionen und Felder zugeordnet werden können, muss in LookML mit dem LookML-Parameter tags angegeben werden, welchen Tags die Felder zugeordnet sind. Bei der Twilio-Nachrichtenaktion wird beispielsweise ein phone-Tag verwendet, damit LookML-Entwickler festlegen können, in welchen Telefonnummernfeldern die Twilio-Aktion angezeigt wird.
  • Aktion auf Dashboard-Ebene:Mit einer Aktion auf Dashboard-Ebene kann ein Bild eines Dashboards gesendet werden. Mit der SendGrid-Aktion werden beispielsweise Dashboard-Bilder per E-Mail gesendet.

Nutzerattribute zu benutzerdefinierten Aktionen hinzufügen

Bei benutzerdefinierten Aktionen können Sie Nutzerattribute im Parameter params Ihrer Aktionsdatei hinzufügen. Wenn der Parameter erforderlich ist, muss für jeden Nutzer in seinem Nutzerkonto oder in einer Nutzergruppe, der er angehört, ein Wert für dieses Attribut definiert sein. Außerdem muss er die send_to_integration-Berechtigung haben, damit die Aktion beim Senden oder Planen von Inhalten als Zieloption angezeigt wird.

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. Definieren Sie einen gültigen Wert für das Nutzerattribut für die Nutzer oder Nutzergruppen, die Inhalte an das Ziel Ihrer Aktion senden müssen. Diese Nutzer müssen auch die Berechtigungen 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 Admin-Bereich konfigurieren muss. Fügen Sie im Parameter params Ihrer Aktionsdatei Folgendes ein:
  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 Nutzerattribute im Bereich Nutzer des Bereichs Verwaltung definiert ist. required: true bedeutet, dass für dieses Nutzerattribut ein gültiger Wert ungleich null definiert sein muss, damit die Aktion bei der Datenübermittlung angezeigt wird. sensitive: true bedeutet, dass das Nutzerattribut verschlüsselt ist und nach der Eingabe nie in der Looker-Benutzeroberfläche angezeigt wird. Sie können mehrere Unterparameter für Nutzerattribute 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. Klicken Sie dazu im Bereich Admin auf der Seite Aktionen neben der Aktion auf die Schaltfläche Aktivieren.
    • 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 mit den Aktionseinstellungen bzw. der Aktivierung muss ein Looker-Administrator die Formularfelder der Aktion so konfigurieren, dass Informationen aus dem Nutzerattribut abgerufen werden. Klicken Sie dazu rechts neben dem entsprechenden Feld auf das Symbol für Nutzerattribute  und wählen Sie das gewünschte Nutzerattribut aus.

requiredField-Parameter in Aktionen auf Zellebene

Für Aktionen auf Zellebene können Sie die LookML-Felder Ihres Modells konfigurieren, um Daten an das Aktionsziel zu senden. 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, wird ein Feld mit diesem Tag abgeglichen. String
any_tag Nein Falls vorhanden, wird tag überschrieben und es wird ein Feld mit einem der angegebenen Tags verwendet. String
all_tags Nein Falls vorhanden, wird tag überschrieben. Es wird ein Feld zurückgegeben, das alle angegebenen Tags enthält. String

Unterstützte Datenformate

Die Klasse DataActionRequest definiert, welches Datenbereitstellungsformat 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 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 Zellebene ist der Wert der Zelle in DataActionRequest enthalten.

Aktion für OAuth konfigurieren

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

OAuth-Ablauf für Looker-Aktionen

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 für die Authentifizierung eines Nutzers für eine Aktion erforderlich sind. Für jede OAuth-fähige oder statusfähige Aktion speichert Looker einen Status pro Nutzer und Aktion, 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. Bei OAuth sollte die /form-Anfrage eine Methode enthalten, um festzustellen, ob der Nutzer im Zieldienst authentifiziert ist. Wenn der Nutzer bereits authentifiziert ist, sollte die Aktion ein normales /form zurückgeben, je nachdem, was für die /execute-Anfrage erforderlich ist. Wenn der Nutzer nicht authentifiziert ist, gibt die Aktion einen Link zurück, mit dem ein OAuth-Ablauf initialisiert wird.

Status mit der OAuth-URL speichern

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

Wenn der Nutzer nicht am Endpunkt authentifiziert ist, sollte das zurückgegebene /form ein form_field vom Typ oauth_link enthalten, das zum /oauth-Endpunkt einer Aktion führt. Die state_url sollte verschlüsselt und als state-Parameter in der 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 /oauth-Endpunkt den Nutzer zum Authentifizierungsserver weiter. Der /oauth-Endpunkt erstellt die Weiterleitung in der oauthUrl(...)-Methode für eine OAuth-Aktion, wie im Dropbox OauthUrl zu sehen ist.

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

Status mit dem Weiterleitungs-URI des Aktions-Hubs speichern

Im /oauth-Endpunkt wird auch ein redirect_uri für den Aktionshub erstellt und an die oauthUrl(...)-Methode der Aktion übergeben. Dieser 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.

Mit diesem Endpunkt wird die Methode oauthFetchInfo(...) aufgerufen, die von der Methode OauthAction implementiert werden sollte, um die erforderlichen Informationen zu extrahieren und zu versuchen, einen vom Authentifizierungsserver empfangenen Status oder auth zu empfangen oder zu speichern.

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

Aktionsdateien zum Looker Action Hub-Repository hinzufügen

Nachdem Sie Ihre Aktionsdatei geschrieben haben, gehen Sie im Looker Action Hub-Repository so vor:

  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ühren Sie alle Tests aus, die Sie geschrieben haben.

yarn test

Aktion testen

Für vollständige Tests können Sie Ihre Aktion in Ihrer Looker-Instanz testen, indem Sie einen privaten Action Hub-Server hosten. Dieser Server muss im öffentlichen Internet mit einem gültigen SSL-Zertifikat verfügbar sein und Verbindungen oder HTTPS-Anfragen von und an 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.

Server für lokale Aktionszentrale einrichten

In diesem Beispiel verwenden wir die Aktion, die wir im GitHub-Repository looker-open-source/actions/src/actions entwickelt haben, und committen den Code in einen neuen Git-Branch. Wir empfehlen, Funktionen in Branches zu entwickeln, damit Sie Ihren Code leichter nachvollziehen und bei Bedarf ganz einfach einen PR mit Looker erstellen können.

  1. Erstellen Sie zuerst einen Branch und führen Sie dann Staging und Commit für Ihre Arbeit durch. Beispiel:

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

  2. Um in diesem Beispiel einen Branch per Push 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, unter der der Aktionshub jetzt gehostet wird. Rufen Sie die URL auf oder führen Sie heroku logs aus, um zu bestätigen, dass der Action-Hub ausgeführt wird. Wenn Sie die öffentliche URL vergessen haben, können Sie den folgenden Befehl 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 Basis-URL des Action Hub fest:

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

  5. Label für den Aktionshub festlegen:

    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 das Secret für den Aktionshub mit dem geheimen Schlüssel fest:

    heroku config:set ACTION_HUB_SECRET="abcdefg123456789"

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

  8. Fügen Sie die Aktion in Ihrer lokalen Looker-Instanz hinzu. Gehen Sie dazu zu Administrator > Aktionen.

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

Wenn für Ihre Aktion bestimmte Arten von Daten von Looker übergeben werden müssen, müssen Sie alle Modelle so konfigurieren, dass der entsprechende tags-Parameter enthalten ist.

Jetzt können Sie Ihre Aktion testen.

Aktionen auf Dashboard- und Abfrageebene testen

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

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

Aktionen auf Zellebene testen

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

Benutzerdefinierte Aktion veröffentlichen und aktivieren

Es gibt zwei Veröffentlichungsoptionen für benutzerdefinierte Aktionen:

Nachdem Ihre Aktion veröffentlicht wurde, können Sie sie im Admin-Bereich auf der Seite Aktionen aktivieren.

Im Looker Action Hub veröffentlichen

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

Nachdem Ihre Aktion getestet wurde, können Sie einen Pull-Request für das Repository looker-open-source/actions auf GitHub senden.

  1. Geben Sie den folgenden Befehl ein:

    git push <your fork> <your development branch>

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

  3. Füllen Sie das Formular zum Einreichen von Inhalten für den Looker Marketplace und den Action Hub aus. Weitere Informationen zu den Formularanforderungen finden Sie unter Inhalte im Looker Marketplace einreichen.

    Looker prüft Ihren Aktionscode. Wir behalten uns das Recht vor, deinen PR abzulehnen, können dir aber bei Problemen helfen und Verbesserungsvorschläge machen. Anschließend führen wir den Code in das looker-open-source/actions-Repository ein und stellen ihn auf actions.looker.com bereit. Sobald der Code bereitgestellt wurde, ist er für alle Looker-Kunden verfügbar.

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

Auf einem privaten Action Hub-Server veröffentlichen

Wenn Sie benutzerdefinierte Aktionen haben, die für Ihr Unternehmen oder Ihren Anwendungsfall privat sind, sollten Sie Ihre Aktion nicht dem looker-open-source/actions-Repository hinzufügen. Erstellen Sie stattdessen einen privaten Action Hub mit demselben Node.js-Framework, das Sie zum Testen Ihrer Aktion verwendet haben.

Sie können Ihren internen Aktionshub-Server auf Ihrer eigenen Infrastruktur oder mit einer cloudbasierten Anwendungsplattform einrichten. In unserem Beispiel wurde Heroku verwendet. Vergessen Sie nicht, den Looker Action Hub vor der Bereitstellung auf Ihren privaten Action Hub-Server zu forken.

LookML-Modell für die 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 mit dem Parameter tags in Ihrem LookML-Modell angeben. Auf der Seite Aktionen im Bereich Admin finden Sie 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 mit Telefonnummern gesendet. Auf der Seite Aktionen im Bereich Admin wird für die Integration der Untertitel „Die Aktion kann mit Abfragen verwendet werden, die ein Feld mit dem Tag phone enthalten“ angezeigt.

Das bedeutet, dass für den Dienst Twilio Send Message eine Abfrage erforderlich ist, die ein Telefonnummernfeld enthält und mit dem Parameter tags das Feld in der Abfrage identifiziert, das die 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 Untertext „Aktion kann mit jeder Anfrage verwendet werden“ angezeigt.

Denken Sie daran, alle erforderlichen Felder in Ihrem LookML-Modell mit dem Parameter tags zu identifizieren, damit Ihre Nutzer Daten über den Dienst senden können.

Nächste Schritte

Informationen zum Bereitstellen der Inhalte eines Looks oder eines Explores oder eines Dashboards für einen integrierten Dienst