Documentation
ドキュメントの検索
karat

+

K

APIリファレンス ↗
Developer toolchainDeveloper Consoleハウツーガイド埋め込みオントロジーでオフライン対応アプリケーションを作成

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

埋め込みオントロジーを使用してオフライン対応アプリケーションを作成する

埋め込みオントロジーを使用すると、アプリケーションでオントロジーデータをローカルに同期でき、ユーザーはネットワーク接続なしでデータを操作したり、アプリケーションをプログレッシブ Web アプリ ↗（PWA）としてインストールしたりできます。このガイドでは、「埋め込みオントロジー React」テンプレートの @palantir/lohi-ts ライブラリを使用して、オフライン対応の Foundry アプリケーションを作成するウォークスルーを紹介します。

前提条件

開始する前に、以下の手順で標準的なアプリケーションのセットアップを完了してください。

  1. Developer Console でクライアント向けアプリケーションを作成します。詳細な手順については、Developer Console を使用してアプリケーションを作成するを参照してください。アプリケーションタイプページで、クライアント向けアプリケーションを選択します。
  2. オントロジーを選択し、含めるオブジェクトタイプを選択します。
  3. アプリケーションの SDKの生成を行います。
  4. サブドメインとリダイレクト URL を含め、Web サイトホスティングを設定します。詳細については、Foundry にカスタムアプリケーションをデプロイするを参照してください。

1. コンテンツセキュリティポリシーで WebAssembly の実行を有効にする

オフライン機能をサポートするために、アプリケーションは WebAssembly（Wasm）を使用します。Wasm の実行を許可するように、コンテンツセキュリティポリシーを設定する必要があります。

  1. Developer Console で、［Web サイトホスティング］に移動し、アドバンスドタブを開きます。
  2. scriptSrc セクションに、単一引用符を含めて 'wasm-unsafe-eval' を追加します。
  3. 右側のプレビューパネルに設定が表示されていることを確認します。

Wasm の設定。

この CSP 設定がないと、デプロイ済みアプリケーションの初期化に失敗します。デプロイする前に必ず設定してください。

2. 埋め込みオントロジー React テンプレートを使用してリポジトリをセットアップする

リポジトリのブートストラッパーを使用して、オントロジー React テンプレートからリポジトリを作成します。

  1. Developer Console で、開発を始める > Foundry でのブートストラップに移動します。
  2. テンプレートのドロップダウンから、埋め込みオントロジー React を選択します。
  3. リポジトリを生成を選択します。

テンプレートのドロップダウン。

テンプレートには、以下の取得元リポジトリが設定されます。

  • osdk-templates-bundle: 埋め込みオントロジー（lohi-ts）のアプリケーションテンプレートを提供します。
  • lohi-asset-bundle: lohi-ts ライブラリと依存関係を含みます。
  • nodejs-bundle: CI/CD 用の Node.js ランタイムです。

3. アプリケーションを設定する

環境設定を確認する

ブートストラッパーは、以下の変数を .env.development と .env.production に設定します。リポジトリの作成後に手動で編集する必要があるのは、.env.production の VITE_FOUNDRY_REDIRECT_URL のみです。

変数用途
VITE_FOUNDRY_API_URLFoundry エンロールメントの URL。
VITE_FOUNDRY_CLIENT_IDアプリケーションの OAuth クライアントID。
VITE_FOUNDRY_REDIRECT_URLOAuth コールバック URL。
VITE_FOUNDRY_ONTOLOGY_RID同期するオントロジーのリソース識別子。
VITE_FOUNDRY_ONTOLOGY_API_NAMEオフライン同期のために lohi-ts が必要とするオントロジーAPI名。

ビルド時に、Vite はこれらの値を <meta> タグとして index.html に挿入し、実行時に src/infra/config.ts が読み込みます。値は .env ファイルで設定するため、src/infra/config.ts を編集する必要はありません。

  1. リポジトリ内の .env.production を開きます。
  2. your-enrollment をエンロールメント名に置き換え、Web サイトのサブドメインで VITE_FOUNDRY_REDIRECT_URL を更新します。
Copied!
1
VITE_FOUNDRY_REDIRECT_URL=https://your-subdomain.your-enrollment.palantirfoundry.com/auth/callback

Developer Console の OAuth 設定に、このリダイレクト URL が含まれていることを確認してください。

同期するオブジェクトを設定する

テンプレートには、空の syncedObjectTypes 配列をエクスポートする src/syncConfig.ts ファイルが含まれています。オフラインで利用可能にするものを選択するために編集する必要があるのは、このファイルのみです。

  1. src/syncConfig.ts を開きます。
  2. 生成した SDK からオブジェクトタイプをインポートし、syncedObjectTypes 配列に追加します。
Copied!
1
2
3
4
import { Employee, Task } from "@your-app/sdk";
import { type SyncConfigParam } from "@palantir/lohi-ts";

export const syncedObjectTypes: SyncConfigParam[] = [Employee, Task];

エントリには、lohi-ts の SyncConfigParam 型を使用します。通常のオブジェクトタイプに加えて、オブジェクトタイプのAPI名の文字列や ObjectSetQuery を渡すことで、そのタイプの絞り込まれたサブセットを同期できます。ピアツーピア同期など、タイプごとのオプションも設定できます。詳細については、@palantir/lohi-ts のドキュメントを参照してください。

ユーザーがオフラインでアクセスする必要のあるオブジェクトのみを含めてください。同期するオブジェクトが多すぎると、初回の読み込み時間とストレージ使用量に影響する可能性があります。

このリストは src/main.tsx の createAppLohiClient に渡され、同期するオブジェクトタイプを Lohi に伝えます。src/router.tsx の <SyncProvider> は、同期のたびにオントロジー SDK のキャッシュ全体を無効化するため、このリストを必要としません。

テンプレートはバックグラウンド同期を自動的に実行します。SyncProvider はマウント時に初回の同期を実行し、同期に成功するたびにオントロジー SDK のキャッシュを無効化します。テンプレートでは、定期的なバックグラウンド同期を有効にするために、syncInterval プロパティが 10_000 ミリ秒（10秒）に設定されています。マウント時と、ユーザーが同期ステータスのピルを選択したときなどのオンデマンド時にのみ同期するには、このプロパティを削除します。src/Home.tsx の <SyncGate> コンポーネントは、初回の同期が完了するまでインターフェースの表示を保留します。

同期を直接実行するには、src/infra/lohi/LohiContext.tsx の useLohiClient フックを使用します。楽観的に適用するのではなく、稼働中の Foundry に到達する必要があるアクションについては、サブツリーを <StandardClientScope> で囲み、src/infra/lohi/useOnlineAction.ts の useOnlineAction フックを使用します。このフックは、アクションに成功した後に再同期を行い、キャッシュを無効化します。

アプリケーションで埋め込みオントロジーを使用する方法の詳細については、生成したリポジトリの README.md を参照してください。

4. アプリケーションを開発する

テンプレートの設定が完了すると、オフラインまたは VS Code ワークスペースでアプリケーションのロジックを開発できます。

  1. 埋め込みオントロジークライアントを使用して、オブジェクトをクエリし、読み込みます。
  2. 必要に応じてアクションや編集を適用します。
  3. テンプレートがオフライン同期を自動的に処理します。

テンプレートには、以下の機能があらかじめ設定されています。

  • プリインストールされた @palantir/lohi-ts の依存関係。
  • Wasm の最適化のために vite.config.ts に組み込まれた lohi-ts Vite プラグイン。
  • src/infra/lohi/client.ts の Lohi クライアントファクトリーと、src/infra/osdk/client.ts の標準オントロジー SDK クライアントファクトリー。どちらも src/infra/auth/oauth.ts の単一の OAuth クライアントを共有します。Lohi がデフォルトのクライアントであるため、@osdk/react フックからの読み取りと書き込みはローカルキャッシュを経由し、書き込みは楽観的に適用されます。
  • マウント時に初回の同期を実行し、同期に成功するたびにオントロジー SDK のキャッシュを無効化し、バックグラウンドで定期的に同期できる SyncProvider。初回の同期が完了するまでインターフェースの表示を保留する <SyncGate> コンポーネントと組み合わせて使用します。
  • オンライン専用アクションのための、2つのクライアントを使い分ける仕組み：<StandardClientScope> と useOnlineAction フックが標準クライアントに対してアクションを実行し、その後に再同期してキャッシュを無効化します。

5. アプリケーションをデプロイする

Foundry の VS Code ワークスペースまたはコードリポジトリのバージョンタグ機能を使用して、アプリケーションのリリース用バージョンタグを作成できます。

タグリリースのオプション。

オフラインで作業している場合は、git タグを使用してアプリケーションをデプロイすることもできます。

Copied!
1
2
git tag 1.0.0
git push origin tag 1.0.0

Code Repositories は、アプリケーションを自動的にビルドし、設定したサブドメインにデプロイします。デプロイのオプションの詳細については、Foundry にカスタムアプリケーションをデプロイするを参照してください。

6. プログレッシブ Web アプリとしてインストールする

アプリケーションをデプロイすると、ユーザーはプログレッシブ Web アプリとしてインストールし、オフラインでアクセスしたり、ネイティブアプリケーションに近い操作感で使用したりできます。

アプリケーションをインストールする

  1. サポートされているブラウザーでデプロイ済みアプリケーションにアクセスします。Chrome、Edge、Safari、その他の Chromium ベースのブラウザーが含まれます。

  2. インストールまたはホーム画面に追加のプロンプトを探します。

    • デスクトップブラウザー： 通常、次のようにアドレスバーにインストールアイコンが表示されます。

      ブラウザーのアドレスバーにあるインストールオプション。

      アドレスバーの右側にあるメニューボタンから、キャスト、保存、共有 > ページをアプリとしてインストール... に移動することもできます。

      ブラウザーでページをアプリとしてインストールするオプション。

    • モバイルブラウザー： ブラウザーメニューにホーム画面に追加の選択肢が表示されます。

  3. インストールを選択し、ブラウザーのプロンプトに従います。

  4. アプリケーションがインストールされ、ネイティブアプリケーションと同じようにデバイスから起動できるようになります。

アプリケーションをオフラインで使用する

インストール後は、インストール済みのアプリやホーム画面からアプリケーションを起動できます。アプリケーションは、同期されたオントロジーデータを使用してオフラインで動作します。接続が復旧すると、アプリケーションは最新のデータを自動的に同期します。ユーザーは、ネットワークにアクセスできなくても、ローカルデータを使って作業を続けられます。

オフラインで利用可能なのは、syncedObjectTypes で設定されたオントロジーオブジェクトのみです。ユーザーがアプリケーションをインストールする前に、適切なオブジェクトを設定していることを確認してください。

ピアリングを有効にする（任意）

デフォルトでは、埋め込みオントロジーがリモートの Foundry から（lohi-ts を介して）データを同期するたびに、設定されたオブジェクトタイプのすべてのオブジェクトを読み込みます。読み込むデータ量によっては、非常に時間がかかることがあります。オブジェクトタイプのピアリングモードを有効にすると、前回の同期からの差分のみが同期され、定期的なデータ同期が大幅に高速化されます。

Ontology Manager で、設定されたオブジェクトタイプごとにオフラインアプリ同期を有効にします。

  1. 機能タブに移動します。

    Ontology Manager の機能タブ。

  2. オフラインアプリ同期モードを有効にします。

    Ontology Manager で特定のオブジェクトタイプのオフラインアプリ同期を有効にする。

  3. データソースタブで、ピアリングオブジェクトデータベースによるオブジェクトタイプのインデックス化が正常に完了するまで待ちます。このデータベースは、ピアリングを通じて接続しているオントロジーのバックエンドサービスです。

    オブジェクトタイプのピアリングのインデックス化の進行状況を監視する。

  4. src/syncConfig.ts で、syncedObjectTypes の該当するエントリーにタイプごとのピアリングオプションを設定します。エントリーはすでに lohi-ts の SyncConfigParam 型を使用しており、この型はオブジェクトタイプごとのピアリングの有効化をサポートしています。詳細については、lohi-ts のドキュメントを参照してください。

よくある問題

CORS エラー

Foundry エンロールメントで、次の CORS が許可されていることを確認してください。

  • 開発：http://localhost:8080
  • 本番環境： Web サイトのサブドメイン

権限がある場合は Control Panel で CORS を設定するか、Foundry 管理者にお問い合わせください。

dev-dist によるビルドの失敗

dev-dist ディレクトリに関連するビルドエラーが表示される場合は、このディレクトリを削除してください。このディレクトリは自動的に生成され、すでに .gitignore に含まれています。

次のステップ

  • 高度な使用パターンについて、テンプレートの README を確認します。
  • ネットワーク接続を無効にして、アプリケーションをオフラインでテストします。
  • カスタムアイコンやスプラッシュ画面など、追加の PWA 機能を設定します。
  • PWA のインストールリンクをユーザーと共有します。