表示されているのは Looker のドキュメントです。Looker Studio のドキュメントについては、https://support.google.com/looker-studio をご覧ください。

埋め込み Looker コンテンツの行レベルのセグメンテーションの実装

著者: シニアデータアナリストの Christopher Seymour、デベロッパーリレーションズエンジニアの Dean Hicks

行レベルのセグメンテーションを使用すると、1 つ以上のデータベースフィールドに保存された値に基づいて、個々のユーザーがアクセスできるデータを制限できます。このガイドでは、埋め込み Looker コンテンツに行レベルのセグメンテーションを実装する方法について説明します。次のセクションが含まれています。

はじめに
- ユースケースの概要
- さらに詳しく
Looker の署名付き埋め込みの基本
- 署名付き埋め込み URL の構造
複数のブランドに同時にアクセスする
- 埋め込み以外の観点からのアプローチ
- 複数のブランドに同時にアクセスする - すべきでないこと
これらのベストプラクティスを活用する
まとめ

はじめに

Looker の埋め込み機能は、Looker プロダクトの最も強力で価値の高い機能の 1 つです。このガイドをお読みの方は、すでに Looker コンテンツをアプリケーションに組み込んでいるか、近い将来に組み込む可能性があります。

このガイドは、Looker の埋め込み機能の設計と、パートナーが複数のブランドへのアクセスを管理できるアプリケーションにセグメンテーションを実装する方法を理解するのに役立ちます。このトピックについては詳しく説明しますが、読みづらくなりますが、このガイドは単純な問題を簡単に修正できるものではなく、Looker の埋め込み全体をより適切に管理するための構成要素であることに留意してください。

ユースケースの概要

このガイドでは、企業が Looker コンテンツをプロダクトに埋め込み、さまざまなデータ部分を表示するユーザーのセグメントを提供する一般的なユースケースについて説明します。

この署名付き埋め込みのユースケースでは、自身が Looker インスタンスの管理者であると想定します。次の 2 種類の外部埋め込みユーザーを使用します。顧客は特定のブランドに関連するデータにのみアクセスでき、パートナーは、複数のブランドのデータにアクセスできます。プロダクトを使用するすべての顧客に表示されるいくつかのタイルを含むダッシュボードがありますが、ダッシュボードにそのお客様に固有のデータのみが表示されるように、顧客ごとに自動的にフィルタする必要があります。このドキュメントの例では、Hooli と Pied Piper の 2 つの架空の会社を使用します。

製品というテーブルがあるとします。このテーブルには、ブランド別の製品指標が表示されます。各ブランドは、署名付き埋め込みアプリケーションの異なる埋め込みユーザー（異なる external_user_id を持つ）に対応しています。各埋め込みユーザーは自分のブランドのデータのみを表示できるため、ブランド ユーザー属性のアクセスフィルタを使用する Explore を作成します。

explore: products {
  access_filter: {
    field: products.brand
    user_attribute: brand
  }
}

この Explore に基づくダッシュボードに、2 つのタイルがあります。1 つはブランドの名前を示し、もう 1 つはブランドの製品数を表示します。

create_sso_embed_url エンドポイントを使用して、埋め込みユーザーごとにこのダッシュボードの埋め込み URL を生成します。この例では、Ped Piper と Hooli の 2 つのブランドを使用しています。以下は、external_user_id pied_piper を指定して Pied Piper の create_sso_embed_url 呼び出しで使用するリクエスト本文です。

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "pied_piper",
  "first_name": "PiedPiper",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper"}
}

Pied Piper 用に生成した URL では、ダッシュボードが次のように表示されます。

次に、Hooli の create_sso_embed_url 呼び出しで使用されるリクエスト本文と external_user_id hooli を示します。

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "hooli",
  "first_name": "Hooli",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Hooli"}
}

Hooli 用に生成された URL では、次のようにダッシュボードが表示されます。

Voilà!ダッシュボードは、各埋め込みユーザーのブランド ユーザー属性の値に従ってフィルタされます。

さらに詳しく

驚きの機能ですね。では、1 人のユーザーに複数のブランドへのアクセス権を付与する場合はどうでしょうか？自分のデータが関連性の高いユーザーだけに表示されるようにするには、どうすればよいですか？

お客様はLooker の署名付き埋め込み機能は、デベロッパーがユーザー向けに強力な独自の仕様に基づくデータエクスペリエンスを作成できるようにすると同時に、データモデルとコンテンツアクセスポリシーで定義されたデータガバナンスを維持できるように設計されています。

その強力なデータエクスペリエンスを提供するには、データガバナンスを徹底的に行うことが非常に重要です。以下では、最適なユーザーエクスペリエンスを設計するためのコンセプトとベストプラクティスをご紹介します。まずは、これらの仕組みの概要を説明します。

Looker の署名付き埋め込みの基本

埋め込みコンテキストにおける Looker のユーザー認証と管理は、基本的には非埋め込みコンテキストと同じ方法で、根本的に他のほとんどのウェブアプリケーションと同様に機能するという点に注意することが重要です。

Looker の署名付き埋め込みのコンテキストでは、署名付き認証ステップ、ユーザー設定、ダッシュボード自体がすべて 1 つの長く複雑な URL に統合されているため、混乱を招く可能性があります。ただし、この URL はセッションを確立するために使用されます。これは URL が短縮された後も適用されます。このコンセプトを念頭に置くことは、優れたデータエクスペリエンスの構築における成功に大いに役立ちます。

署名付き埋め込み URL の構造

Pied Piper のリクエスト本文を含む create_sso_embed_url 呼び出しによって生成される署名付き埋め込み認証 URL は次のとおりです。

https://mylookerinstance.cloud.looker.com/login/embed/%2Fembed%2Fdashboards%2F17?permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%5D&models=%5B%22thelook%22%5D&signature=iG6vcKBgnA50jaL2iShFeQHwFPN7wvTx7Rz6r%2FtFuvE%3D&nonce=%22967729518a7dbb8a178f1c03a3511dd1%22&time=1696013242&session_length=300&external_user_id=%22pied_piper%22&access_filters=%7B%7D&first_name=%22Pied%22&last_name=%22Piper%22&user_attributes=%7B%22brand%22%3A%22Pied+Piper%22%7D&force_logout_login=true

同じ URL をデコードして個別の行に分割すると、次のようになります。

https://mylookerinstance.cloud.looker.com/login/embed/
/embed/dashboards/17
?permissions=["access_data","see_user_dashboards"]
&models=["thelook"]
&signature=iG6vcKBgnA50jaL2iShFeQHwFPN7wvTx7Rz6r/tFuvE=
&nonce="967729518a7dbb8a178f1c03a3511dd1"
&time=1696013242
&session_length=300
&external_user_id="pied_piper"
&access_filters={}
&first_name="PiedPiper"
&last_name="User"
&user_attributes={"brand":"Pied Piper"}
&force_logout_login=true

この URL にアクセスすると、次のことが起こります。

Looker は external_user_id = pied_piper の既存のユーザーアカウントを探します。存在しない場合、Looker はその external_user_id を使用して新しいユーザーアカウントを作成します。
権限、モデル、グループ（指定されている場合）、ユーザー属性値（指定されている場合）など、既存のユーザーのアカウントの詳細は、URL で指定されたアカウントの詳細で上書きされます。
Looker はユーザーを認証し、ブラウザにセッション Cookie を保存してそのユーザーのセッションを確立します。
その後、Looker は、create_sso_embed_url 呼び出しで指定されたターゲット URL またはリダイレクト URL にリダイレクトします。

https://mylookerinstance.cloud.looker.com/embed/dashboards/17。

このリダイレクト URL は、エンコードされた相対 URL として元の署名付き埋め込み URL で確認できます。

%2Fembed%2Fdashboards%2F17

ステップ 1 ～ 3 はバックグラウンドで自動的に行われ、すべてのエンドユーザーが最終結果（ダッシュボード自体）に表示されますが、これらのステップは基本的に、埋め込み以外の通常の Looker ユーザーが認証するステップと同じです。ユーザーが、ユーザー名とパスワードの認証情報を使用してログインするとします。このプロセスは次のようになります。

Looker 管理者は、[Admin - Users] パネルに移動し、検索バーを使用して、このユーザーのユーザーアカウントがすでに存在するかどうかを確認します。そうでない場合は、新しいユーザーアカウントを作成します。
Looker 管理者は [Admin - Users] パネルでユーザーの横にある [編集] をクリックし、権限、モデル、グループ、ユーザー属性値などの値でユーザーをプロビジョニングします。
ユーザーが https://mylookerinstance.cloud.looker.com/login のログインページにアクセスし、ユーザー名とパスワードを入力します。Looker はユーザーを認証し、ブラウザにセッション Cookie を保存してそのユーザーのセッションを確立します。
その後、Looker はランディングページ（通常は https://mylookerinstance.cloud.looker.com/browse）にリダイレクトします。

セッション Cookie はブラウザウィンドウのすべてのタブに適用されます。ユーザーが https://mylookerinstance.cloud.looker.com/browse から開始して新しいブラウザタブを開き、ユーザーの権限でアクセスできる任意のページに移動すると、元のブラウザタブですでに確立されているセッション Cookie を使用して、ページが想定どおりに読み込まれます。

埋め込みユーザーも同様です。埋め込みユーザーには、UI でアクセスできるページがさらに制限されます。アクセスできる URL は、/embed 接頭辞が付いた Look、ダッシュボード、Explore の URL のみです。ただし、ユーザーアカウントの詳細によってアクセス権が付与されているダッシュボードには、引き続き手動で移動できます。元の署名付き埋め込み URL から、1 つのブラウザタブで https://mylookerinstance.cloud.looker.com/embed/dashboards/17 にリダイレクトされるとします。次に、新しいブラウザタブを開き、同じフォルダ（したがって、アクセス制限が同じ）にある別の埋め込みダッシュボード https://mylookerinstance.cloud.looker.com/embed/dashboards/19 を読み込みます。

元の署名付き埋め込み URL で指定されたリダイレクト URL はダッシュボード 17 用ですが、ブラウザタブに URL を手動で入力すれば、ダッシュボード 19 が想定どおりに読み込まれることを確認できます。別のダッシュボードを読み込むために、別の署名付き埋め込み URL は必要ありません。

ここでの重要なインサイトは、URL で確立されたすべてのユーザーアカウントの詳細（権限、ユーザー属性など）が、元の署名付き URL で指定された特定のダッシュボードだけでなく、ユーザーセッション全体に適用されることです。つまり、その名前が示すように、ユーザー属性はダッシュボードの機能ではなくユーザーの機能であり、1 つの特定のタブだけでなく、アプリケーション全体の特定のユーザーのアクセスレベルを決定するために使用する必要があります。

複数のブランドに同時にアクセスする

また、複数のブランドを所有または管理する外部パートナーがいるとします。この例では、パートナーが Pied Piper と Hooli の両方のブランドを管理しています。

埋め込み以外の観点からのアプローチ

署名付き埋め込みユーザーセッションは、通常の埋め込み以外の Looker ユーザーセッションと基本的に同じように機能するため、前述した問題のあるアプローチを通常の埋め込み以外の Looker ユーザーセッションのコンテキストで捉え直し、そのステップを分解することで、このソリューションをより堅牢に実装する方法を理解するのに役立ちます。Looker UI にアクセスできる標準の BI ユーザーに指示を出す場合、そのワークフローは次のようになります。

[Admin - Users] ページで、2 つの異なるユーザーアカウントを作成します。
1. 最初のユーザーアカウントの編集ページで、ブランド ユーザー属性値を pied_piper に設定します。
2. 2 番目のユーザーアカウントの編集ページで、ブランド ユーザー属性値を hooli に設定します。
両方のユーザーアカウントのアカウント設定メールをパートナーに送信します。
パートナーは、アカウントごとに個別のメールとパスワードの認証情報を設定します。
ダッシュボードへのリンクをパートナーに提供します。（https://mylookerinstance.cloud.looker.com/dashboards/17）。ブランド間でダッシュボードを切り替えるには、別のタブのログインページに戻り、他のユーザーアカウントのメールとパスワードの認証情報を入力してから、そのタブで再度ダッシュボードに表示されます。

パートナーは手順に沿って操作を行います。ただし、2 番目のブラウザタブで Hooli ユーザーアカウントのユーザー名とパスワードを入力した後で、Piped Piper ダッシュボードがすでに読み込まれている最初のタブに戻り、パートナーが[再読み込み] ボタンをクリックします。驚くべきことに、ダッシュボードには Hooli のデータが表示されます。

ここで、こう考えるかもしれません。

少し不便です。どうすればいいですか？

はい、できます。これらのシナリオが、埋め込み以外のコンテキストではすでに自明であるが、埋め込みコンテキストの抽象化によって難読化される可能性がある原則を説明しています。1 人のユーザーを、単一のユーザー属性値のセットを持つ単一の Looker ユーザーアカウントに関連付ける必要がありますこれは、署名付き埋め込みのドキュメントにある external_user_id の説明でも明確に示されています。

Looker では、署名付き埋め込みユーザーの区別に external_user_id が使用されるため、各ユーザーに一意の ID を割り当てる必要があります。

任意の文字列を持つユーザーの external_user_id は、そのユーザーに固有のものであれば作成できます。各IDは、権限、ユーザー属性、モデルのセットに関連付けられています。1 つのブラウザが一度にサポートできるのは、1 つの external_user_id またはユーザーセッションだけです。セッション内でユーザーの権限やユーザー属性を変更することはできません。

複数のブランドに同時にアクセスする - すべきでないこと

カスタマイズ可能な他のソリューションと同様に、使用すべきではないアプローチも存在します。たとえば、前述の create_sso_embed_url 呼び出しで同じ入力を使用して両方の external_user_ids の URL をアプリで生成し、パートナーがアクセスする必要がある各ダッシュボードを読み込むために、アプリに新しいタブを作成する実装です。デベロッパーがこのようなソリューションを実装することはよくあり、結果としてユーザーのワークフローは不正確となります。

Pied Piper ダッシュボードのタブに移動します。
Hooli ダッシュボードのタブに移動します。
Pied Piper ダッシュボードのタブに戻ります。
Pied Piper ダッシュボードで [再読み込み] ボタンをクリックします。

Pied Piper ダッシュボードには Hooli のデータが表示されます。

同様の方法を試すこともできますが、代わりに両方の create_sso_embed_url 呼び出しに同じ external_user_id test_user を使用してください。ただし、動作はまったく同じです。タブが Pied Piper ダッシュボードで再読み込みされると、代わりに Hooli のデータが表示されます。

各ブランドのダッシュボードにそのブランドのデータのみを表示するにはどうすればよいですか？

ベストプラクティスを実践する

埋め込み以外の視点からのアプローチセクションで説明されているアプローチを適用するには、アプリケーション全体でパートナーがアクセスする必要があるすべてのデータへのアクセス権を付与する、単一のユーザー属性値が必要です。これを行うには、ブランド属性（Pied Piper,Hooli）のカンマ区切りの値を使用します。

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

この構文が機能するためには、ユーザー属性が [String Filter (advanced)] に設定されていることを確認する必要があります。

データアクセスレベルに変更が加えられた場合、ユーザーのユーザー属性のセットを変更できます。たとえば、パートナーが 3 番目のブランドの所有権を取得している場合は、ブランド ユーザー属性に指定したカンマ区切りリストにその 3 番目のブランドを追加できます。こうすることで、ユーザーがログアウトして再度ログインしたときに、変更が適用されます。

ダッシュボード結果のフィルタリング

わかりました。ユーザー属性では、ユーザーがアプリケーション全体でアクセスできるすべてのデータを指定する必要があります。しかし、この方法でユーザー属性を指定すると、これらすべてのブランドのデータがダッシュボードに表示されます。特定のダッシュボードの結果を特定のブランドに絞り込むにはどうすればよいですか？

特定のダッシュボードをフィルタする正しい方法は、通常のダッシュボードフィルタを使用することです。（これは明白なように思えるかもしれませんが、埋め込みコンテキストでフィルタを適用する唯一の方法としてのユーザー属性に行き詰まる人々もいます。おそらく、user_attributes は署名付き埋め込み URL のパラメータであり、フィルタはそうではないためです）。

必ずフィルタ値を必須にして、プルダウンなどの単一選択コントロールオプションのいずれかを使用してください。

必要なすべてのタイルの正しいフィールドにフィルタが適用されていることを確認します。

プルダウンで使用できるオプションはユーザー属性によって制限されるため、パートナーはこれらの 2 つの値（この 2 つのみ）を選択できます。

ダッシュボードフィルタの事前入力

これで、ダッシュボードを特定のブランドでフィルタできるようになりました。ただし、ユーザーがアプリでそのブランドのダッシュボードを読み込んだときに、フィルタの値をすでに特定のブランドに設定したいとします。

ここでも、埋め込み以外のコンテキストでこれがどのように機能するかを考えておくと役立ちます。特定のフィルタ値がすでに適用されているダッシュボードへのリンクを他のユーザーに送るにはどうすればよいですか？フィルタ値を選択すると、そのフィルタ値がダッシュボードの URL に表示されます。

create_sso_embed_url 呼び出し用の target_url に URL のその部分を含めます。

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17?Brand=Hooli",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

埋め込み SDK を使用している場合は、withFilters を使用して、埋め込みコンテンツに適用する初期フィルタを指定できます。

https://looker-open-source.github.io/embed-sdk/classes/EmbedBuilder.html#withFilters

独自のカスタムスクリプトを使用している場合は、パスがエンコードされる前にフィルタを URL に追加していることを確認してください。一部の値はすでにフィルタ文字列でエンコードされている可能性があります（たとえば、?Brand=Pied+Piper に + としてエンコードされるスペースがある場合）。それらの値は最終ページ URL では二重エンコードされます。詳しくは、SO 埋め込みダッシュボード - URL の一部としてダッシュボードフィルタを設定しますか？をご覧ください。こうしたニュアンスに関するディスカッションの Looker コミュニティ投稿。フィルタの適用がうまくいかない場合は、こちらのコミュニティ投稿で質問をご投稿ください。

ダッシュボードフィルタの非表示

ダッシュボードに初期フィルタを設定する方法はわかりましたが、パートナーがダッシュボードフィルタを自分で変更しないようにしたいのですが、フィルタ値は、パートナーがどのダッシュボードにアクセスしたかによってのみ決定する必要があります。ダッシュボードフィルタを非表示にするにはどうすればよいですか？

これにはテーマを使用できます。テーマは有料機能であるため、Looker インスタンスでまだ有効にしていない場合は、Looker のセールスチームに連絡して有効にしてもらう必要があります。

この機能を有効にしたら、[Admin - Themes] ページの [ダッシュボードのコントロール] セクションに移動し、[フィルタバーを表示] オプションの選択を解除します。

次に、テーマをデフォルトとして設定するか、特定のダッシュボードの URL でテーマを適用します。この場合も、create_sso_embed_url 呼び出しの target_url に入ります。

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17?Brand=Hooli&theme=test_theme",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

一部の埋め込み SDK コードスニペットなど、埋め込みダッシュボードフィルタを非表示にする方法について詳しくは、この YouTube チュートリアルのカスタムフィルタを使用して Looker を埋め込むをご覧ください。

最終的な結果は、元の質問のユーザーエクスペリエンスと同じになります。

現在は、アプリに埋め込まれているそれぞれのターゲット URL にフィルタ値がエンコードされているため、各ブランドのダッシュボードには、タブを行き来しても、適切なブランドにフィルタされたダッシュボードが常に表示されます。

他のユーザーとしてテストする

現在、ユーザーエクスペリエンスは当初の想定にかなり近いものになりました。ただし、このユースケースでは、パートナーには external_user_id=pied_piper や external_user_id=hooli を持つ個々のユーザーにはない異なる権限やユーザー設定があるため、UI で使用できるオプションが異なり、全体的にユーザーエクスペリエンスが若干異なります。 pied_piper や hooli のユーザーと同じように、あたかもそれらのユーザーとしてログインしたかのように、ユーザーがすべてを見ることができるようにしたいのです。どうすればいいですか？

ユーザーが個々のブランドユーザーとしてテストできるようにする場合は、同様の sudo 関数をアプリに構築して、ユーザーが Pied Piper ユーザーとして sudo を実行しているときに external_user_id=pied_piper の埋め込み URL を読み込みこみ、Hooli ユーザーとして sudo を実行しているときに external_user_id=hooli の埋め込み URL を読み込むことができます。また、アプリで API を使用する場合は、login_user API エンドポイントを使用して、API を持つブランドユーザーとして sudo を行うこともできます。

ただし、非埋め込みコンテキストについてもう一度考えてみましょう。[Admin - Users] ページで、複数のタブで複数の非埋め込みユーザーとして sudo を同時に行うことはできません。sudo セッションは、他のすべてのユーザーセッションと同様に、ブラウザウィンドウ全体に適用されます。そのため、一度に 1 人だけのユーザーとして sudo を実行する sudo を設計する必要があります。考えてみると、この設計は、sudo を実行しているユーザーのエクスペリエンスを完全に模倣しています。たとえば、pied_piper ユーザーは Pied Piper ダッシュボードにのみアクセスでき、追加タブで追加ダッシュボードを開くことはできません。そのため、このユーザーとして sudo を実行している場合は、別のタブで別のダッシュボードを開くことはできません。

まとめ

このガイドがお役に立てば幸いです。Looker の署名付き埋め込みコンテンツを作成する準備が整ったと感じていらっしゃることでしょう。Google は、Looker を最も柔軟で堅牢な組み込み型データ分析サービスの開発に取り組んでおります。皆様からのご意見をお待ちしています。ご質問がある場合や詳細については、Looker コミュニティで交流し、コミュニティイベントにご参加ください。