Daten über einen Aktions-Hub freigeben

Zusätzlich zur Bereitstellung von Inhalten in den integrierten Zielen von Looker können Sie mithilfe von Aktionen – auch Einbindungen genannt – Inhalte an Drittanbieterdienste, die über Looker eingebunden sind, über einen Action Hub-Server bereitstellen.

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

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

Die folgende Grafik veranschaulicht die verfügbaren Workflow-Optionen für die Einbindung von Aktionen über einen privat gehosteten Aktions-Hub oder den von Looker gehosteten Aktions-Hub:

Nachdem die Aktion zum Aktions-Hub hinzugefügt wurde, kann ein Looker-Administrator sie für die Bereitstellung von Looker-Inhalten an diese Dienste aktivieren.

Sie können auch mehrere Aktions-Hubs einrichten, wenn Sie die Looker-Integrationen über den Looker Action Hub nutzen 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 Admin angezeigt.

Der Looker Action Hub

Looker hostet und stellt den Looker Action Hub zur Verfügung, einen zustandslosen Server, der die Looker's Action API implementiert und beliebte Aktionen verfügbar macht. 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 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 in der Lage sein, mit der Looker-Instanz zu kommunizieren und diese Anforderungen zu erfüllen. Administratoren, die von Kunden gehostete Instanzen verwenden, müssen unter Umständen zusätzliche Faktoren berücksichtigen, wenn sie Looker-Integrationen aus dem Looker Action Hub aktivieren. Das gilt insbesondere, wenn sie 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 diese Anfragen nicht unterstützt 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 kundenseitig 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 diese 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

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

Eine Streamingaktion ermöglicht es der Aktion, Abfragen zu verarbeiten, die Alle Ergebnisse liefern. Für Aktionen, bei denen OAuth aktiviert ist, wird die nutzerspezifische Authentifizierung über OAuth 2.0-Abläufe verwendet. OAuth-Aktionen müssen Nutzeranmeldedaten in ihrer Quell-Looker-Instanz speichern, da der Looker Action Hub zustandslos und mehrmandantenfähig ist und keine nutzerspezifischen Anmeldedaten jeglicher Art gespeichert werden.

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 an 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 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 durch Looker gehosteten Instanzen, die die Zulassungsliste für IP-Adressen aktiviert haben, müssen diese IP-Adressen hinzufügen, um Aktionen verwenden 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 in der Lage sein, mit der Looker-Instanz zu kommunizieren und diese Anforderungen zu erfüllen. Dies ist aus verschiedenen Gründen nicht immer bei vom Kunden gehosteten Looker-Instanzen möglich. Wenn eine bidirektionale Kommunikation zwischen Looker Action Hub und der Looker-Instanz nicht möglich ist, kann Looker Action Hub unerwartetes oder unerwünschtes Verhalten zeigen, z. B. das Aufhängen von Abfragen oder nicht verfügbare Aktionen.

Um das potenzielle Problem zu beheben, dass Looker Action Hub nicht mit der Looker-Instanz kommunizieren kann, können Looker-Administratoren eine der folgenden Lösungen implementieren. 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 – das heißt, der Looker Action Hub kann keine Anfragen von der Looker-Instanz empfangen – können Looker-Administratoren ihren Looker-Account Manager bitten, die Lizenzfunktion public_host_url zu aktivieren. Diese Lizenzfunktion zeigt die Startoption --public-host-url 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, bei dem public_host_url als öffentlich auflösbarer Name angegeben ist. Dieser Reverse-Proxy akzeptiert nur Anfragen von den statischen IP-Adressen für ausgehenden Traffic für den Looker Action Hub. Looker-Administratoren, die diese Methode verwenden, müssen der Zulassungsliste für ausgehenden Traffic die IP-Adressen hinzufügen, von denen der Looker Action Hub Anfragen an die Looker-Instanz sendet: 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. Um dieses Problem zu beheben, müssen Looker-Administratoren der IP-Adresse des ausgehenden Traffics, von 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.

  • Zum Bereitstellen eines vom Kunden gehosteten Aktions-Hubs 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 dafür, dass die OAuth- und Streamingaktionen auf einer vom Kunden gehosteten Looker-Instanz nicht verwendbar sind, liegt daran, dass die Instanz ein SSL-Zertifikat verwendet, das von einer Zertifizierungsstelle (Certificate Authority, CA) ausgestellt wurde, die nicht auf dieser Liste aufgeführt ist.

Benutzerdefinierte Aktion erstellen

In diesem Abschnitt werden die Schritte zum Schreiben und Testen einer benutzerdefinierten Aktion mit dem Looker Action Hub-Quellcode beschrieben. Beispiele für funktionale Codes finden Sie im Repository looker-open-source/actions in GitHub.

So erstellen Sie eine benutzerdefinierte Aktion:

  1. Entwicklungs-Repository einrichten
  2. Aktion schreiben
  3. Aktion testen
  4. Veröffentlichen und aktivieren Sie Ihre Aktion entweder im Looker Action Hub oder auf Ihrem eigenen privaten Aktions-Hub-Server.

Wie bei jeder Aktion müssen Sie möglicherweise Ihre LookML-Modelle mit bestimmten Parametern konfigurieren, bevor Sie die Aktion zum Liefern Ihrer Daten verwenden 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-Code, mit der Typinformationen hinzugefügt werden, um Programmierfehler zu erkennen. Wenn Sie mit JavaScript vertraut sind, sollte Ihnen der Großteil der TypeScript-Sprache vertraut sein.

Für das Ausführen des Looker Action Hub ist 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 ein Verzeichnis mit dem Namen Ihrer Aktion im Verzeichnis actions/src/actions. Beispiel:

    mkdir actions/src/actions/my_action

  3. Füllen Sie das Verzeichnis mit den Dateien, die Sie zum Ausführen Ihrer Aktion benötigen. Eine Beispieldateistruktur finden Sie im Aktionen GitHub-Repository.

Looker empfiehlt Folgendes:

  • Eine README-Datei, die den Zweck und die Mittel der Authentifizierung für deine Aktion erklärt
  • PNG-Symbol, das im Looker Action Hub (oder dem privaten Aktions-Hub 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 ist nicht das Gleiche wie das Testen Ihrer Aktion

Aktion schreiben

Eine Designanforderung für den Looker Action Hub-Server besteht darin, dass er vollständig zustandslos bleibt. Daher ist das Speichern von Informationen in der Aktion oder im Dienst nicht zulässig. Alle Informationen, die zur Ausführung der Aktion erforderlich sind, müssen in den Anfrageaufrufen der Aktionsdatei angegeben sein.

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 Ihrer Aktion erforderlich sind. Es gibt auch die Methode /form, mit der zusätzliche Informationen vom Nutzer erfasst werden können, bevor die Aktion ausgeführt wird. Die Felder, die Sie in der /form angeben, werden im Pop-up-Fenster Senden oder Planen angezeigt, wenn Nutzer die Aktion als Ziel für ihre Datenübermittlung auswählen.

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

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

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 für Menschen lesbares Label für die Aktion. String
supportedActionTypes Ja Eine Liste der 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 Aktivierungsseite der Aktion im Steuerfeld Admin angezeigt werden. Wenn Sie festlegen möchten, wie Nutzer Daten für ein Aktionsziel bereitstellen können, geben Sie ein Nutzerattribut an, für das der Nutzer einen bestimmten Wert haben muss. Weitere Informationen parameters
supportedFormats Nein Eine Liste der Datenformate, die von der Aktion unterstützt werden. Gültige Werte: "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 der Formatierungsoptionen für die Visualisierung, 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 von Beschreibungen 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 unbegrenztes Streaming von Daten zu ermöglichen. Der Parameter wird durch den Parameter usesStreaming festgelegt, der ein boolescher Wert true/false ist. 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 an die Aktion ein einmalig gesendeter Link gesendet wird, mit dem Sie state für einen bestimmten Nutzer für diese Aktion festlegen können. Boolesch
usesStreaming Nein Ein boolescher Wert, mit dem festgelegt wird, ob die Aktion gestreamte Abfrageergebnisse unterstützt. Prüfen Sie in der Liste der integrierten Dienste die Spalte Ergebnisse können mit „Ja“ oder „Nein“ gestreamt werden. Für Aktionen, die Ergebnisse streamen, ist möglicherweise die Konfiguration eines lokalen Aktions-Hub-Servers erforderlich. Weitere Informationen finden Sie im Artikel Lokalen Aktions-Hub für Aktionen mit OAuth oder Streaming einrichten in der Looker-Hilfe. Boolesch
minimumSupportedVersion Nein Die minimale Looker-Version, in der die Aktion in der Aktions-Hub-Liste Admin angezeigt wird. String

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

Unterstützte Aktionstypen

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

  • Aktion auf Suchanfragenebene: Eine Aktion, die eine gesamte Abfrage sendet. Die Segmentaktion ist beispielsweise eine Aktion auf Abfrageebene.
  • Eine Aktion auf Zellenebene: Eine Aktion auf Zellebene sendet den Wert einer einzelnen Zelle in einer Datentabelle. Dieser Aktionstyp unterscheidet sich von Datenaktionen, die für Dimensionen oder Messwerte mit dem Parameter action definiert werden können. Zum Senden von Informationen aus einer bestimmten Zelle innerhalb einer Tabelle verwendet Looker Tags, um Aktionen den entsprechenden Zellen zuzuordnen. 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 werden sollen. Die Twilio Message Action verwendet beispielsweise ein phone-Tag, damit LookML-Entwickler steuern können, welche Telefonnummernfelder die Twilio-Aktion anzeigt.
  • Aktion auf Dashboard-Ebene: Eine Aktion auf Dashboard-Ebene unterstützt das Senden eines Bildes eines Dashboards. Zum Beispiel sendet die Crawl-Aktion Dashboard-Bilder per E-Mail.

Nutzerattribute zu benutzerdefinierten Aktionen hinzufügen

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

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, wenn es noch nicht vorhanden ist.
  2. Legen Sie einen gültigen Wert für das Nutzerattribut der 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 Aktivierungsseite der Aktion in der Liste Aktionen im Steuerfeld Admin konfigurieren muss. Geben Sie im Parameter params Ihrer 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 (Nutzerattribute) auf der Seite Users (Nutzerattribute) des Steuerfelds Admin 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 erkannt wird. sensitive: true bedeutet, dass das Nutzerattribut verschlüsselt ist und nach der Eingabe in der Looker-UI nie angezeigt wird. Sie können mehrere Nutzerattribut-Unterparameter angeben.

  1. Stellen Sie Ihre Aktualisierungen auf dem Aktions-Hub-Server bereit.
    • Wenn Sie eine neue Aktion hinzufügen, muss ein Looker-Administrator die Aktion aktivieren. Dazu klickt er im Steuerfeld Admin auf der Seite Aktionen neben der Aktion auf die Schaltfläche Aktivieren.
    • Wenn Sie eine vorhandene Aktion aktualisieren möchten, aktualisieren Sie die Liste der Aktionen, indem Sie auf die Schaltfläche Aktualisieren klicken. Klicken Sie dann auf Einstellungen.
  2. Auf der Seite mit den Aktionseinstellungen/-aktivierungen muss ein Looker-Administrator die Formularfelder konfigurieren, um Informationen aus dem Nutzerattribut abzurufen. Dazu klickt er rechts neben dem entsprechenden Feld auf das Nutzerattributsymbol und wählt 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 dieses Aktionsziel zu übergeben. Geben Sie dazu im Parameter requiredFields Ihrer Aktionsdatei an, welche Tags von Ihrer Aktion unterstützt werden.

Parameter Erforderlich Beschreibung Datentyp
tag Nein Stimmt mit einem Feld mit diesem Tag überein. String
any_tag Nein Wenn vorhanden, ersetzt tag den Wert und stimmt mit einem Feld mit einem der angegebenen Tags überein. String
all_tags Nein Wenn dieses Feld vorhanden ist, hat es Vorrang vor tag und entspricht einem Feld mit allen bereitgestellten Tags. String

Unterstützte Datenformate

Die Klasse DataActionRequest definiert, mit welchem Format der Datenübermittlung die Aktion ausgeführt werden kann. Bei Aktionen auf Suchanfragenebene 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 Zellebene ist der Wert der Zelle auf DataActionRequest vorhanden.

Aktion für OAuth konfigurieren

OAuth-fähige Aktionen können nicht über Looker Action Hub für Looker-Instanzen konfiguriert werden, für die die Funktion IP-Zulassungsliste aktiviert ist oder die die Looker Action Hub-Anforderungen nicht erfüllen können. Weitere Informationen zum Konfigurieren einer Aktion für OAuth finden Sie in der Looker-Hilfe im Artikel zum Einrichten eines lokalen Hubs für Aktionen, die OAuth oder Streaming verwenden.

Sie können Ihre Aktion so konfigurieren, dass sich Nutzer mit OAuth bei der 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 erforderlich sind, um einen Nutzer in einer Aktion zu authentifizieren. Für jede OAuth-aktivierte oder staatlich aktivierte Aktion speichert Looker den Status pro Nutzer und Aktion, sodass jede Aktion und Nutzerkombination ein unabhängiges OAuth-Ereignis hat.

Der Ablauf zum Erstellen von Aktionen umfasst normalerweise eine /form-Anfrage gefolgt von einer /execute-Anfrage. Für OAuth sollte die Anfrage /form eine Methode enthalten, um festzustellen, ob der Nutzer im Zieldienst authentifiziert ist. Wenn der Nutzer bereits authentifiziert ist, sollte die Aktion gemäß den Anforderungen von /execute eine normale /form zurückgeben. Wenn der Nutzer nicht authentifiziert ist, gibt die Aktion einen Link zurück, mit dem ein OAuth-Ablauf initialisiert wird.

Status wird mit der OAuth-URL gespeichert

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

Wenn der Nutzer nicht beim Endpunkt authentifiziert ist, sollte die zurückgegebene /form einen form_field vom Typ oauth_link enthalten, der an den /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 unter Dropbox OauthUrl gezeigt.

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

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

Am Endpunkt /oauth wird auch ein redirect_uri für den Aktions-Hub erstellt und an die Methode oauthUrl(...) übergeben. redirect_uri hat die Form /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, alle vom Authentifizierungsserver empfangenen Status oder auth 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 an diese Aktion sendet, wird der neu gespeicherte Status an den Looker Action Hub gesendet.

Aktionsdateien zum Looker Action Hub-Repository hinzufügen

Sobald Ihre Aktionsdatei geschrieben wurde, 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ühren Sie alle von Ihnen geschriebenen Tests aus.

yarn test

Aktion testen

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

  1. Erstellen Sie zuerst Ihren Branch und stellen Sie die Arbeit auf die Bühne und führen Sie einen Commit durch. 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 jetzt der Aktions-Hub gehostet wird. 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 haben, können Sie in der Befehlszeile Folgendes 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 Label für den Aktions-Hub 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 Ihr Autorisierungstoken zurück. Beispiel: Authorization: Token token="abcdefg123456789"

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

    heroku config:set ACTION_HUB_SECRET="abcdefg123456789"

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

  8. Fügen Sie die Aktion der lokalen Looker-Instanz hinzu, indem Sie zu Admin > Aktionen gehen.

    • 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 von Looker übergeben werden müssen, müssen Sie alle Modelle so konfigurieren, dass sie den entsprechenden Parameter tags enthalten.

Sie können Ihre Aktion jetzt testen.

Aktionen auf Dashboard- und Abfrageebene testen

Falls erforderlich, konfigurieren Sie das LookML-Modellin Ihrer Looker-Instanz mit Tags. Erstellen Sie einen Look und speichern Sie ihn. Klicken Sie im gespeicherten Look auf das Menü oben rechts und wählen Sie Senden mit Ihrer Aktion als Ziel aus. Wenn Sie ein Formular für die Zustellung haben, rendert Looker es im Fenster Gesendet.

Klicken Sie auf Test senden, um die Daten bereitzustellen. Der Status der Aktion wird im Planerverlauf im Steuerfeld Admin angezeigt. Wenn bei Ihrer Aktion ein Fehler auftritt, wird sie im Steuerfeld Admin angezeigt und Looker sendet 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 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ü die Option Senden aus. Wenn Sie Fehler erhalten, müssen Sie die Datentabelle vollständig aktualisieren, nachdem Sie diese Fehler behoben haben.

Benutzerdefinierte Aktion veröffentlichen und aktivieren

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

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

Im Looker Action Hub veröffentlichen

Dieser Ansatz ist am einfachsten und funktioniert für jede Aktion, die Sie für Nutzer von Looker verfügbar machen 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 Ihre Pull-Anfrage mit dem Ziel looker-open-source/actions als Ziel.

  3. Füllen Sie das Formular zum Einreichen von Aktions-Hub für Looker Marketplace 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 in das looker-open-source/actions-Repository zusammen 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 für Ihr Unternehmen oder Ihren Anwendungsfall privat sind, sollten Sie Ihre Aktion 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 Aktions-Hub-Server in Ihrer eigenen Infrastruktur oder mit einer cloudbasierten Anwendungsplattform einrichten, in unserem Beispiel Heroku. Vergessen Sie vor der Bereitstellung nicht, den Looker Action Hub auf den privaten Hub des Servers zu übertragen.

LookML-Modell für die Verwendung mit einer 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 mithilfe des Parameters tags in Ihrem LookML-Modell bestimmen.

Auf der Seite Aktionen im Steuerfeld Admin finden Sie Informationen zu den Tags, die für den Dienst gegebenenfalls erforderlich sind. Beispiel:

Die Zapier-Integration gibt an, dass sie mit jeder Abfrage funktioniert. Es ist nicht erforderlich, den Parameter tags einem Feld in Ihrem LookML-Modell hinzuzufügen.

Der Twilio Send Message-Dienst sendet jedoch eine Nachricht an eine Liste von Telefonnummern. Sie erfordert eine Abfrage, die ein Telefonnummernfeld enthält, und bestimmt anhand des Parameters tags, 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 ;;
}

Sie müssen alle erforderlichen Felder in Ihrem LookML-Modell mit dem Parameter tags angeben, damit Ihre Nutzer den Dienst zum Senden von Daten verwenden können.

Daten mit einer Aktion liefern

Ihre Daten können auf verschiedene Arten übermittelt werden, je nachdem, auf welcher Ebene die Aktion ausgeführt wird. Aktionen werden auf Feld-, Abfrage- oder Dashboardebene 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:

Daten über Mobilfunk senden

Aktionen auf Feldebene sind auf der Seite Aktionen des Steuerfelds Verwaltung durch eine Beschreibung gekennzeichnet, die „Aktion kann mit Feldern verwendet werden kann“ oder mit einem Ja in der Spalte Kann aus Feldern verwendet werden in der Liste der integrierten Dienste enthalten.

Aktionen auf Feldebene sind dafür ausgelegt, eine Datenzelle an den angegebenen Dienst zu 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 ein Maß zu definieren, müssen Sie Ihr LookML-Modell konfigurieren. Dazu kennzeichnen Sie die relevanten Felder mit den Informationen aus der Spalte 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. Sehen Sie sich die Daten an, die Sie in einem Look, einem Dashboard oder einer explorativen Datenanalyse bereitstellen möchten. Wenn der Dienst "&Action" mit Abfragen verwenden kann, die mit einem getaggten Feld versehen sind, muss Ihre Abfrage oder eine der Kacheln des Dashboards ein oder mehrere Felder mit allen erforderlichen Tags enthalten.

  2. Das getaggte Feld in jeder Zelle im Bereich „Look“, „Dashboard“ oder „Erkunden“ enthält eine Drop-down-Liste mit Auslassungspunkten (...). Klicken Sie auf die drei Punkte, um die für diesen Link verfügbaren Aktionen aufzurufen:

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

Dashboard- oder Abfragedaten bereitstellen

Aktionen auf Suchanfragenebene sind auf der Seite Aktionen des Steuerfelds Admin durch eine Beschreibung gekennzeichnet, die Folgendes enthält: „Aktion kann mit Abfragen verwendet werden, die ein getaggtes Feld haben“ oder „Aktion kann mit jeder Abfrage verwendet werden“. Gemäß der Spalte Darf senden oder planen in der Liste der integrierten Dienste können Sie Jede Zeile (in einem Look oder eine Erkundung) bereitstellen. 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 Steuerfelds Admin durch eine Beschreibung gekennzeichnet, die Folgendes enthält: „Aktion kann mit jedem Dashboard verwendet werden.“ Gemäß der Spalte Können gesendet oder geplant in der Liste der integrierten Dienste können Sie ein Dashboard bereitstellen. Aktionen auf Dashboard-Ebene sind so konzipiert, dass sie ein Dashboard an den angegebenen Dienst liefern.

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

Wenn Sie einen Look oder eine Erkundung bereitstellen möchten, rufen Sie die Dokumentationsseite Looks und Entdeckungen auf.

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