Neben der Bereitstellung von Inhalten an die integrierten Looker-Ziele können Sie mit Aktionen – auch als Integrationen bezeichnet – Inhalte an Drittanbieterdienste senden, die über einen Action Hub-Server in Looker eingebunden sind.
Auf dieser Seite erfahren Sie, wie Sie benutzerdefinierte Aktionen erstellen, die Sie dem Looker Action Hub oder Ihrem eigenen Private Action Hub-Server hinzufügen können. Auf dieser Seite wird auch beschrieben, wie Sie einen lokalen Action Hub-Server einrichten, um Ihre benutzerdefinierten Aktionen zu testen oder einen privaten Action Hub-Server auszuführen.
Um Aktionen zu verwenden, haben Sie folgende Möglichkeiten:
- Sie können die vorhandenen Aktionen von Looker verwenden, die im Looker Action Hub verfügbar sind.
- Erstellen Sie eine benutzerdefinierte Aktion und veröffentlichen Sie sie zur öffentlichen Nutzung im Looker Action Hub.
- Erstellen Sie eine benutzerdefinierte Aktion und veröffentlichen Sie sie zur privaten Nutzung auf einem Hub-Server für private Aktionen.
Nachdem die Aktion dem Action Hub hinzugefügt wurde, kann ein Looker-Administrator die Aktion für die Bereitstellung von Looker-Inhalten an diese Dienste enable.
Sie können auch mehrere Action Hubs einrichten, wenn Sie die Integrationen von Looker über den Looker Action Hub verwenden und auch Ihre eigenen privaten oder benutzerdefinierten Aktionen hosten möchten. Die Aktionen für jeden Action Hub werden im Admin-Bereich auf der Seite Aktionen angezeigt.
Der Looker Action Hub
Looker hostet und stellt den Looker Action Hub bereit, einen zustandslosen Server, der die Action API von Looker implementiert und beliebte Aktionen anzeigt. Alle Daten, die Ihre Benutzer über eine Aktion senden, werden vorübergehend auf dem Looker Action Hub-Server und nicht in Ihrer Looker-Instanz verarbeitet.
Looker ist bereits in verschiedene Dienste integriert. Auf der Dokumentationsseite Administratoreinstellungen – Aktionen erfahren Sie, wie Sie diese vorhandenen Dienste aktivieren.
Anforderungen an den Looker Action Hub
Der Looker Action Hub muss API-Anfragen auf folgende Weise senden und empfangen können:
- Von der Looker-Instanz zum Looker Action Hub-Netzwerk
- Vom Browser des Looker-Nutzers zum Looker Action Hub-Netzwerk
- Vom Looker Action Hub-Netzwerk zur Looker-Instanz
Wenn Ihre Looker-Bereitstellung diese Anfragen nicht verarbeiten kann oder die Funktion IP-Zulassungsliste für Ihre Looker-Instanz aktiviert ist, können Sie einen lokalen Action-Hub-Server für private Looker-Integrationen oder benutzerdefinierte Aktionen einrichten. Administratoren von vom Kunden gehosteten Instanzen können auch einen lokalen Aktionsserver speziell für OAuth- und Streaming-Aktionen bereitstellen.
Anfragen von der Looker-Instanz an das Looker Action Hub-Netzwerk
Anfragen an actions.looker.com
werden zu einer dynamischen 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 Looker-Benutzerbrowser an das Looker Action Hub-Netzwerk
Der Browser des Looker-Nutzers muss Anfragen an die folgenden Looker Action Hub-Endpunkte senden können (für OAuth):
actions.looker.com/actions/<name>/oauth
Dabei ist name
der programmatische Name der Aktion.
Anfragen vom Looker Action Hub-Netzwerk an die Looker-Instanz
Der Looker Action Hub muss Anfragen für Aktionen an die Looker-Instanz senden, die gestreamte Ergebnisse unterstützen oder OAuth verwenden.
Eine Streamingaktion ermöglicht es der Aktion, Abfragen zu verarbeiten, die Alle Ergebnisse liefern. Für OAuth-fähige Aktionen wird die Authentifizierung pro Nutzer über OAuth 2.0-Abläufe verwendet. OAuth-Aktionen müssen Benutzeranmeldedaten in ihrer Quellinstanz von Looker speichern, da der Looker Action Hub zustandslos und mandantenfähig ist und keine benutzerspezifischen Anmeldedaten speichert.
Die Anfragen vom Looker Action Hub an eine Looker-Instanz haben folgende 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>
einer IP-Adresse zuzuordnen und Anfragen an das Netzwerk zu senden, in dem sich Ihre Looker-Instanz befindet.
Der Looker Action Hub hat statische ausgehende IP-Adressen, von denen die Anfragen immer kommen: 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 verwenden zu können, die gestreamte Ergebnisse unterstützen oder OAuth verwenden.
Überlegungen zu vom Kunden gehosteten Instanzen
Damit Sie Looker-Integrationen verwenden können, muss der Looker Action Hub mit der Looker-Instanz kommunizieren können und die Looker Action Hub-Anforderungen erfüllen. Dies ist mit vom Kunden gehosteten Looker-Instanzen aus verschiedenen Gründen nicht immer möglich. Wenn keine bidirektionale Kommunikation zwischen dem Looker Action Hub und der Looker-Instanz möglich ist, kann der Looker Action Hub ein unerwartetes oder unerwünschtes Verhalten aufweisen, z. B. hängende 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 gezeigt 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 durch den 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-Vertriebsexperten kontaktieren, um die Lizenzfunktion
public_host_url
zu aktivieren. Diese Lizenzfunktion zeigt die Startoption--public-host-url
, 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 einige bestimmte Looker Action Hub-Callback-URLs und leitet diese Callback-URLs über einen Reverse-Proxy weiter, dessenpublic_host_url
als öffentlich auflösbarer Name verwendet wird. 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 die ausgehenden IP-Adressen, von denen der Looker Action Hub Anfragen an die Looker-Instanz sendet, auf die Zulassungsliste setzen:35.153.89.114
,104.196.138.163
und35.169.42.87
.Wenn die URL der vom Kunden gehosteten Instanz durch die Looker-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 lösen, müssen Looker-Administratoren die IP-Adressen für ausgehenden Traffic, von denen aus der Looker Action Hub Anfragen an die Looker-Instanz sendet, auf die Zulassungsliste setzen:
35.153.89.114
,104.196.138.163
und35.169.42.87
.Wenn keine der oben genannten Lösungen für die Looker-Instanzarchitektur geeignet ist, können Looker-Administratoren einen vom Kunden gehosteten Action Hub für alle Aktionen oder nur für Aktionen bereitstellen, die gestreamte Ergebnisse unterstützen oder OAuth verwenden.
Um einen vom Kunden gehosteten Action Hub bereitzustellen, müssen Sie dafür sorgen, dass die JAR-Datei auf einem öffentlichen Server gehostet wird, damit der Looker Action Hub mit ihr kommunizieren kann. Diese Lösung wird jedoch nicht empfohlen.
Außerdem können die OAuth- und Streaming-Aktionen auf einer vom Kunden gehosteten Looker-Instanz möglicherweise nicht verwendet werden, wenn die Instanz ein SSL-Zertifikat verwendet, das von einer Zertifizierungsstelle ausgestellt wurde, die nicht in dieser Liste der Root-Zertifikate enthalten ist.
Benutzerdefinierte Aktion erstellen
In diesem Abschnitt werden die Schritte zum Schreiben und Testen einer benutzerdefinierten Aktion mit dem Looker Action Hub-Quellcode beschrieben. Funktionale Codebeispiele finden Sie in den vorhandenen Aktionen im looker-open-source/actions
-Repository in GitHub.
So erstellen Sie eine benutzerdefinierte Aktion:
- Entwicklungs-Repository einrichten
- Aktion schreiben
- Aktion testen
- Aktion veröffentlichen und aktivieren, 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 zur Bereitstellung Ihrer Daten verwenden können.
Entwicklungs-Repository einrichten
Der Looker Action Hub ist ein Node.js-Server, der in TypeScript geschrieben ist. Dabei handelt es sich um eine kleine Schicht auf modernem JavaScript, die Typinformationen hinzufügt, um Programmierfehler zu erkennen. Wenn Sie mit JavaScript vertraut sind, sollten Ihnen die meisten der TypeScript-Sprache vertraut sein.
Zum Ausführen des Looker Action Hub ist folgende Software erforderlich:
- Node.js
- Node Version Manager (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.
Klonen Sie das Repository
looker-open-source/actions
lokal:git clone git@github.com:looker-open-source/actions.git
Erstellen Sie im Verzeichnis
actions/src/actions
ein Verzeichnis mit dem Namen Ihrer Aktion. Beispiel:mkdir actions/src/actions/my_action
Füllen Sie Ihr Verzeichnis mit den Dateien, die Sie zur Ausführung der Aktion benötigen. Eine Beispieldatei für die Dateistruktur finden Sie im GitHub-Repository für Aktionen.
Looker empfiehlt, dass Sie auch Folgendes hinzufügen:
- Eine README-Datei, in der der Zweck und die Methoden der Authentifizierung für Ihre Aktion erläutert werden
- Ein PNG-Symbol, das im Looker Action Hub (oder im privaten Action Hub auf Ihrer Looker-Instanz) und in den Looker-Datenübermittlungsfenstern angezeigt wird
- Dateien für Tests, die Sie mit Ihrem Aktionscode ausführen möchten – dies unterscheidet sich vom Testen der Aktion.
Aktion schreiben
Eine Designanforderung für den Looker Action Hub-Server besteht darin, dass er vollständig zustandslos bleibt, sodass das Speichern von Informationen in der Aktionsanwendung oder im Dienst nicht zulässig ist. Alle Informationen, die zum Ausführen der Aktion erforderlich sind, müssen in den Anfrageaufrufen der Aktionsdatei angegeben werden.
Der genaue Inhalt der Aktionsdatei richtet sich nach dem Dienst, dem Typ oder der Ebene, auf der die Aktion ausgeführt wird, und 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
. An Looker API-Anfragen wird jedes Mal ein DataActionRequest
übergeben, wenn ein Nutzer die Aktion in Looker ausführt. DataActionRequest
enthält alle Daten und Metadaten, die zum Ausführen der Aktion erforderlich sind. Außerdem ist eine /form
-Methode verfügbar, mit der zusätzliche Informationen vom Nutzer erfasst werden können, bevor er die Aktion ausführt. 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.
Fügen Sie beim Schreiben der Aktionsdatei mindestens die folgenden Parameter ein, die als erforderlich gekennzeichnet sind:
Parameter | Erforderlich | Beschreibung | Datentyp |
---|---|---|---|
name |
Yes | Ein eindeutiger Name für die Aktion. Dieser sollte für alle Aktionen im Looker Action Hub eindeutig sein. | String |
url |
Yes | Eine absolute URL des /execute -Endpunkts für diese Aktion. |
String |
label |
Yes | Ein für Menschen lesbares Label für die Aktion. | String |
supportedActionTypes |
Yes | Eine Liste der Aktionstypen, die die Aktion unterstützt. 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. Diese Felder werden auf der Aktivierungsseite der Aktion im Admin-Bereich angezeigt. Sie können ein Nutzerattribut angeben, für das ein Nutzer einen definierten Wert haben muss, um zu verwalten, wie Nutzer Daten an ein Aktionsziel senden können. |
parameters |
supportedFormats |
Nein | Eine Liste der Datenformate, die die Aktion unterstützt. Gültige Werte sind "txt" , "csv" , "inline_json" , "json" , "json_detail" |
String |
supportedFormattings |
Nein | Eine Liste der von der Aktion unterstützten Formatierungsoptionen. Gültige Werte sind "formatted" und "unformatted" . |
String |
supportedVisualizationFormattings |
Nein | Eine Liste der von der Aktion unterstützten Formatierungsoptionen für Visualisierungen. Gültige Werte sind "apply" und "noapply" . |
String |
iconName |
Nein | Ein Daten-URI, der ein Symbolbild für die Aktion darstellt. | String |
requiredFields |
Nein | Eine Liste mit Beschreibungen von Pflichtfeldern, 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 bestimmt, ob der Aktion eine einmalige Download-URL gesendet wird, um ein unbegrenztes Streaming von Daten zu ermöglichen. Der Parameter wird durch den Parameter usesStreaming festgelegt, bei dem es sich um einen booleschen true/false -Wert handelt. Wenn usesStreaming = true , dann supportedDownloadSettings = url . Wenn usesStreaming = false , dann supportedDownloadSettings = push . |
Boolesch |
usesOAuth |
Nein | Ein boolescher Wert, der bestimmt, ob es sich bei der Aktion um eine OAuth-Aktion handelt. Damit wird festgelegt, ob an die Aktion ein Einmallink gesendet wird, über den Sie state für einen bestimmten Nutzer für diese Aktion festlegen können. |
Boolesch |
usesStreaming |
Nein | Ein boolescher Wert, der bestimmt, ob die Aktion gestreamte Abfrageergebnisse unterstützt. Klicken Sie in der Liste der integrierten Dienste das Kästchen Verwendet Datenstreaming (Ja/Nein) an. Aktionen, die Ergebnisse streamen, erfordern möglicherweise die Konfiguration eines lokalen Action Hub-Servers. Weitere Informationen finden Sie auf der Seite mit den Best Practices unter Lokalen Action Hub für Aktionen einrichten, die OAuth oder Streaming verwenden. | Boolesch |
minimumSupportedVersion |
Nein | Die Looker-Mindestversion, in der die Aktion in der Action Hub-Liste im Bereich Admin angezeigt wird. | String |
Beispiele aus Looker Action Hub-Aktionen finden Sie auf GitHub als Referenz.
Unterstützte Aktionstypen
Looker unterstützt drei Arten von Aktionen, wie im Parameter supportedActionTypes
Ihrer Aktion angegeben: Abfrage, Zelle und Dashboard.
- Aktion auf Abfrageebene: Mit dieser Aktion wird eine vollständige Abfrage gesendet. Die Segmentaktion ist beispielsweise eine Aktion auf Abfrageebene.
- Aktion auf Zellenebene:Bei einer Aktion auf Zellenebene wird der Wert einer einzelnen, bestimmten Zelle in einer Datentabelle gesendet. Dieser Aktionstyp unterscheidet sich von Datenaktionen, die mit dem Parameter
action
für Dimensionen oder Messwerte definiert werden können. Um Informationen aus einer bestimmten Zelle in einer Tabelle zu senden, verwendet Looker Tags, um den entsprechenden Zellen Aktionen zuzuordnen. Für Aktionen muss angegeben werden, welche Tags inrequiredFields
unterstützt werden. Zum Zuordnen von Aktionen und Feldern müssen Felder in LookML angeben, welchen Tags sie mit dem LookML-tags
-Parameter zugeordnet werden. Die Twilio-Nachrichtenaktion verwendet beispielsweise einphone
-Tag, damit LookML-Entwickler steuern können, für welche Telefonnummernfelder die Twilio-Aktion angezeigt wird. - Eine Aktion auf Dashboard-Ebene: Eine Aktion auf Dashboard-Ebene unterstützt das Senden des Bilds eines Dashboards. Die SendGrid-Aktion sendet beispielsweise Dashboard-Bilder per E-Mail.
Nutzerattribute zu benutzerdefinierten Aktionen hinzufügen
Bei benutzerdefinierten Aktionen können Sie dem Parameter params
Ihrer Aktionsdatei Nutzerattribute hinzufügen. Wenn der Parameter erforderlich ist, muss jeder Nutzer zusätzlich zur Berechtigung send_to_integration
einen Wert für dieses Attribut in seinem Nutzerkonto oder für eine Nutzergruppe definiert haben, der er angehört, damit die Aktion beim Senden oder Planen von Inhalten als Zieloption angezeigt wird.
So fügen Sie Ihrer Aktion ein Nutzerattribut hinzu:
- Möglicherweise muss ein Looker-Administrator das Nutzerattribut erstellen, das dem
user_attribute_param
entspricht, falls es noch nicht vorhanden ist. - Definieren Sie einen gültigen Wert für das Nutzerattribut für die Nutzer oder Nutzergruppen, die Inhalte an Ihr Aktionsziel übermitteln müssen. Diese Nutzer benötigen außerdem Berechtigungen des Typs
send_to_integration
. - Der Parameter
params
steht für die Formularfelder, die ein Looker-Administrator auf der Aktivierungsseite der Aktion im Bereich Admin in der Liste Aktionen konfigurieren muss. Fügen Sie im Parameterparams
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 auf der Seite Nutzerattribute im Bereich Nutzer des Admin-Bereichs im Feld Name definiert ist. required: true
bedeutet, dass für dieses Nutzerattribut ein gültiger Wert definiert werden muss, der nicht null ist, damit beim Senden von Daten die Aktion angezeigt wird. sensitive: true
bedeutet, dass das Nutzerattribut verschlüsselt ist und nie in der Looker-Benutzeroberfläche angezeigt wird, nachdem es eingegeben wurde. Sie können mehrere Unterparameter für Nutzerattribute angeben.
- Stellen Sie die Updates auf dem Action Hub-Server bereit.
- Wenn Sie eine neue Aktion hinzufügen, muss ein Looker-Administrator sie aktivieren. Dazu klickt er im Steuerfeld Admin neben der Aktion auf der Seite Aktionen 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.
- Auf der Seite „Aktionseinstellungen“/„Aktion“ 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 so konfigurieren, dass Daten an dieses Aktionsziel gesendet werden. Geben Sie dazu im requiredFields
-Parameter Ihrer Aktionsdatei an, welche Tags Ihre Aktion unterstützt.
Parameter | Erforderlich | Beschreibung | Datentyp |
---|---|---|---|
tag |
Nein | Falls vorhanden, entspricht dies einem Feld mit diesem Tag. | String |
any_tag |
Nein | Falls vorhanden, ersetzt es tag und stimmt mit einem Feld überein, das eines der angegebenen Tags enthält. |
String |
all_tags |
Nein | Falls vorhanden, ersetzt es tag und stimmt mit einem Feld überein, das alle angegebenen Tags enthält. |
String |
Unterstützte Datenformate
Die Klasse DataActionRequest
definiert, welches Datenübermittlungsformat für die Aktion verfügbar ist. Bei Aktionen auf Abfrageebene enthält die Anfrage einen Anhang, der verschiedene Formate haben 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 ist der Wert der Zelle in DataActionRequest
vorhanden.
Aktion für OAuth konfigurieren
Sie können Ihre Aktion so konfigurieren, dass sich Nutzer mit OAuth für die Aktion authentifizieren können. Auch wenn der Looker Action Hub zustandslos bleiben muss, können Sie einen Status über eine Formularanfrage über die Looker Action API erzwingen.
OAuth-Ablauf für Looker-Aktion
Für Aktionen im Looker Action Hub können Sie ein OAuthAction
anstelle eines Hub.Action
erweitern, um einen booleschen Wert festzulegen, der angibt, welche OAuth-Methoden zum Authentifizieren eines Nutzers für eine Aktion erforderlich sind. Für jede OAuth- oder Status-aktivierte Aktion speichert Looker einen pro Benutzer und pro Aktion aktivierten Status, sodass jede Aktion und Benutzerkombination ein unabhängiges OAuth-Ereignis aufweist.
Der Ablauf zum Erstellen von Aktionen umfasst normalerweise eine /form
-Anfrage gefolgt von einer /execute
-Anfrage. Für OAuth sollte die /form
-Anfrage 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 der /execute
-Anfrage eine normale /form
zurückgeben. Wenn der Nutzer nicht authentifiziert ist, gibt die Aktion einen Link zurück, der einen OAuth-Ablauf initialisiert.
Status wird mit OAuth-URL gespeichert
Looker sendet eine HTTP-POST-Anfrage mit einem leeren Textkörper an den ActionList
-Endpunkt. Wenn die Aktion in ihrer Definition uses_oauth: true
zurückgibt, wird in jeder /form
-Anfrage von Looker eine einmalige state_url
gesendet. Die state_url
ist eine spezielle einmalige URL, die den Status eines Nutzers für eine bestimmte Aktion festlegt.
Wenn der Nutzer bei dem Endpunkt nicht authentifiziert ist, sollte die zurückgegebene /form
eine form_field
vom Typ oauth_link
enthalten, die zum Endpunkt /oauth
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 Endpunkt /oauth
den Nutzer an den Authentifizierungsserver weiter. Der Endpunkt /oauth
erstellt die Weiterleitung in der oauthUrl(...)
-Methode für eine OAuth-Aktion, wie in der Dropbox-OauthUrl gezeigt.
Der Parameter state
, der diese verschlüsselte state_url
enthält, sollte an den Looker Action Hub übergeben werden.
Status wird mit dem Weiterleitungs-URI des Action Hub gespeichert
Im Endpunkt /oauth
wird auch eine redirect_uri
für den Action Hub erstellt und an die Methode oauthUrl(...)
der Aktion übergeben. Dieser 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 durch die 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.
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 zum Looker Action Hub-Repository hinzufügen
Nachdem Sie Ihre Aktionsdatei geschrieben haben, gehen Sie im Looker Action Hub-Repository so vor:
Fügen Sie die Aktionsdatei (z. B.
my_action.ts
) zuactions/src/actions/index.ts
hinzu.import "./my_action/my_action.ts"
Fügen Sie alle Node.js-Paketanforderungen hinzu, die Sie beim Schreiben der Aktion verwendet haben. Beispiel:
yarn add aws-sdk yarn add express
Installieren Sie die Node.js-Abhängigkeiten des Looker Action Hub-Servers.
yarn install
Führen Sie alle von Ihnen geschriebenen Tests aus.
yarn test
Aktion testen
Für vollständige Tests können Sie Ihre Maßnahme gegen Ihre Looker-Instanz testen, indem Sie einen privaten Action-Hub-Server hosten. Dieser Server muss sich im öffentlichen Internet mit einem gültigen SSL-Zertifikat befinden und Verbindungen oder HTTPS-Anfragen zu und von Looker initiieren und empfangen können. Dazu können Sie eine cloudbasierte Plattform wie Heroku verwenden, wie im folgenden Beispiel gezeigt. Alternativ können Sie eine beliebige Plattform verwenden, die die oben genannten Anforderungen erfüllt.
Lokalen Action-Hub-Server einrichten
In diesem Beispiel führen wir die Aktion aus, die wir im GitHub-Repository looker-open-source/actions/src/actions
entwickelt haben, und übergeben den Code an einen neuen Git-Zweig. Wir empfehlen, mit Branches an Features zu arbeiten, damit Sie Ihren Code einfach verfolgen und bei Bedarf problemlos eine PR mit Looker erstellen können.
Erstellen Sie zuerst Ihren Zweig und stellen Sie dann Ihre Arbeit bereit und übernehmen Sie sie. Beispiel:
git checkout -b my-branch-name git add file-names git commit -m commit-message
Um in diesem Beispiel einen Zweig an Heroku zu übertragen, konfigurieren Sie Ihr Git-Repository mit Heroku als Remote-Option in der Befehlszeile:
heroku login heroku create git push heroku
Heroku gibt die öffentliche URL zurück, auf der jetzt der Action Hub gehostet wird. Rufen Sie die URL auf oder führen Sie
heroku logs
aus, um zu prüfen, ob der Action Hub ausgeführt wird. Wenn Sie die öffentliche URL vergessen haben, können Sie Folgendes in der Befehlszeile ausführen:heroku info -s | grep web_url
Heroku gibt Ihre öffentliche URL zurück. Beispiel:
https://my-heroku-action-server-1234.herokuapp.com
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"
Legen Sie ein Label für den Action Hub fest:
heroku config:set ACTION_HUB_LABEL="Your Action Hub"
Looker verwendet ein Autorisierungstoken, um eine Verbindung zum Action Hub herzustellen. Generieren Sie das Token über die Befehlszeile:
heroku run yarn generate-api-key
Wenn Sie nicht Heroku verwenden, wie in diesem Beispiel, verwenden Sie stattdessen:
yarn generate-api-key
Heroku gibt dann Ihr Autorisierungstoken zurück. Beispiel:
Authorization: Token token="abcdefg123456789"
Legen Sie das Secret für den Action Hub mit dem geheimen Schlüssel fest:
heroku config:set ACTION_HUB_SECRET="abcdefg123456789"
Für vom Kunden gehostete Bereitstellungen können die Konfiguration zusätzlicher Umgebungsvariablen erforderlich sein, die hier nicht dokumentiert sind.
Fügen Sie die Aktion auf Ihrer lokalen Looker-Instanz hinzu, indem Sie Verwaltung > Aktionen aufrufen.
- Klicken Sie unten in der Liste der Aktionen auf Add Action Hub.
- Geben Sie die Action Hub-URL und optional einen Sicherheitsschlüssel ein.
- Sie finden Ihre Aktion im Looker-Menü Admin in der Liste Aktionen.
- Klicken Sie auf Aktivieren.
Wenn Ihre Aktion erfordert, dass bestimmte Arten von Daten von Looker übergeben werden, müssen Sie alle Modelle konfigurieren, die den entsprechenden tags
-Parameter enthalten.
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 und speichern Sie einen Look. Klicken Sie im gespeicherten Look oben rechts auf das Menü und wählen Sie Senden mit Ihrer Aktion als Ziel aus. Wenn Sie ein Formular zur Verfügung stellen, wird es von Looker im Fenster Gesendet gerendert.
Klicken Sie auf Send Test (Test senden), um die Daten zu senden. Der Status der Aktion wird im Planerverlauf im Admin-Bereich angezeigt. Wenn bei der Aktion ein Fehler auftritt, wird dieser im Admin-Bereich angezeigt. 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 Ihrer Looker-Instanz eine Abfrage aus, die dieses Feld enthält. Suchen Sie das Feld in der Datentabelle. Klicken Sie in der Zelle auf … und wählen Sie im Drop-down-Menü … aus. Wenn Fehler auftreten, müssen Sie die Datentabelle vollständig aktualisieren, nachdem Sie diese Fehler behoben haben.
- Wenn Ihre Aktion fehlerfrei bereitgestellt wird, können Sie die Aktion veröffentlichen.
- Wenn Sie Ihre Aktion weiterhin privat hosten möchten, können Sie diese in Ihrem privaten Action Hub veröffentlichen.
- Wenn Sie Ihre Aktion zur Verwendung durch alle Looker-Kunden veröffentlichen möchten, lesen Sie den Abschnitt Im Looker Action Hub veröffentlichen.
Benutzerdefinierte Aktion veröffentlichen und aktivieren
Es gibt zwei Veröffentlichungsoptionen für benutzerdefinierte Aktionen:
- Im Looker Action Hub veröffentlichen: Ihre Aktion wird dadurch allen Nutzern zur Verfügung gestellt, die Looker verwenden.
- Auf einem privaten Action-Hub-Server veröffentlichen: Dadurch wird die Aktion nur auf Ihrer Looker-Instanz verfügbar.
Nach der Veröffentlichung der Aktion können Sie sie im Admin-Bereich auf der Seite Aktionen aktivieren.
Im Looker Action Hub veröffentlichen
Dieser Ansatz ist der einfachste und funktioniert für jede Aktion, die Sie jedem Benutzer von Looker zur Verfügung stellen möchten.
Nachdem die Aktion getestet wurde, kannst du eine PR an das looker-open-source/actions
-Repository in GitHub senden.
Geben Sie den folgenden Befehl ein:
git push <your fork> <your development branch>
Erstellen Sie die Pull-Anfrage mit dem Repository
looker-open-source/actions
als Ziel.Füllen Sie das Übermittlungsformular für Looker Marketplace und Action Hub aus. Weitere Informationen zu den Formularanforderungen finden Sie unter Inhalte an den Looker Marketplace senden.
Looker überprüft Ihren Aktionscode. Wir behalten uns das Recht vor, Ihre PR abzulehnen, können Ihnen aber bei Problemen helfen und Verbesserungsvorschläge unterbreiten. Anschließend führen wir den Code im Repository
looker-open-source/actions
zusammen und stellen ihn inactions.looker.com
bereit. Sobald der Code bereitgestellt ist, steht er allen Looker-Kunden zur Verfügung.Aktivieren Sie die Aktion in Ihrer Looker-Instanz, damit sie als Option für die Datenübermittlung angezeigt wird.
Auf einem Private Action Hub-Server veröffentlichen
Wenn Sie benutzerdefinierte Aktionen haben, die auf Ihr Unternehmen oder Ihren Anwendungsfall beschränkt sind, sollten Sie sie nicht dem Repository looker-open-source/actions
hinzufügen. Erstellen Sie stattdessen einen privaten Action Hub mit demselben Node.js-Framework, das Sie zum Testen Ihrer Aktion verwendet haben.
Sie können Ihren internen Aktions-Hub-Server auf Ihrer eigenen Infrastruktur oder über eine cloudbasierte Anwendungsplattform (in unserem Beispiel mit Heroku) einrichten. Vergessen Sie nicht, den Looker Action Hub vor der Bereitstellung mit Ihrem Private Action Hub-Server zu verknüpfen.
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 mithilfe des Parameters tags
in Ihrem LookML-Modell identifizieren. Auf der Seite Aktionen im Bereich Admin finden Sie Informationen zu den Tags, die gegebenenfalls für den Dienst erforderlich sind.
Beispielsweise sendet eine Integration von Twilio Send Message eine Nachricht an eine Liste mit Telefonnummern. Auf der Seite Aktionen im Admin-Bereich wird bei der Integration der Untertext „Action kann mit Abfragen verwendet werden, deren Feld mit dem Tag phone
versehen ist“ angezeigt.
Dies bedeutet, dass der Twilio Send Message-Dienst eine Abfrage erfordert, die ein Telefonnummernfeld enthält und mithilfe des tags
-Parameters ermittelt, 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 ;;
}
Bei einer Integration, für die keine Tags erforderlich sind, wird im Bereich Admin auf der Seite Aktionen der Untertext „Action kann mit jeder Abfrage verwendet werden“ angezeigt.
Achten Sie darauf, alle Pflichtfelder in Ihrem LookML-Modell mit dem Parameter tags
zu identifizieren, damit Ihre Nutzer den Dienst zum Senden von Daten verwenden können.
Nächste Schritte
Erfahren Sie, wie Sie die Inhalte eines Looks oder Explores oder eines Dashboards an einen integrierten Dienst übermitteln können.