ユースケース開発Slateデータの読み書きSlateでのOntology SDK (OSDK)の使用

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

Slate でオントロジー SDK を使用する

Ontology Software Development Kit（オントロジー SDK）を使用すると、アプリの作成者は Slate のコード環境内でオントロジーの機能を最大限に活用できます。オントロジー SDK は関数エディター内のライブラリとして利用可能で、オントロジーのオブジェクトタイプ、リンクタイプ、アクション、関数に型安全にアクセスできます。

Slate のオントロジー SDK は、TypeScript オントロジー SDK と同じ基盤 API を使用します。Slate は JavaScript を使用しますが、コード補完と型ヒントのために IntelliSense を提供します。

概要

Slate のオントロジー SDK パネルでは、次のことができます。

使用するオントロジーを選択する
オブジェクトタイプ、リンクタイプ、アクションタイプ、関数などのデータエンティティを設定する
選択したエンティティに合わせたカスタムのオントロジー SDK ライブラリを生成する
各エンティティのドキュメントとコードスニペットを表示する
アプリケーションに変更を確定する前に、変更を確認する

はじめに

オントロジー SDK パネルにアクセスする

Slate アプリケーションを編集モードで開きます。
左側のサイドバーで OSDK アイコンを選択して、オントロジー SDK パネルを開きます。
オントロジー SDK をまだ設定していない場合は、オントロジーの選択画面が表示されます。

オントロジーを選択する

オントロジーを選択ドロップダウンから、アクセスするオントロジーを選択します。
選択を確定を選択して、選択内容を保存します。

利用可能なオントロジーは、プラットフォームのセットアップと権限によって異なります。アクセスできるオントロジーが1つだけの場合もあります。後で別のオントロジーに切り替えるには、オントロジー SDK を削除して再設定する必要があります。

オントロジー SDK パネルの「オントロジーを選択」ドロップダウンが表示されたオントロジーの選択画面。

データエンティティを追加する

オントロジーを選択すると、オントロジー SDK の設定に4種類のエンティティを追加できます。

オブジェクトタイプとリンクタイプ

オブジェクトタイプは、オントロジーの主要なデータエンティティを表します。リンクタイプはオブジェクトタイプ間の関係を定義し、親オブジェクトタイプの下にネストして表示されます。

オブジェクトタイプセクションで、+ ボタンを選択します。
検索ダイアログを使用して、オブジェクトタイプを検索して選択します。
オブジェクトタイプを選択すると、関連するリンクタイプが自動的に利用可能になります。
依存関係は自動的に解決されるため、リンクタイプを追加すると、必要なオブジェクトタイプも含まれます。

アクションタイプ

アクションタイプを使用すると、オントロジーのデータを変更する操作を実行できます。

アクションタイプセクションで、+ ボタンを選択します。
必要なアクションタイプを検索して選択します。
アクションに必要なオブジェクトタイプの依存関係は、自動的に追加されます。

関数

関数を使用すると、オントロジーで定義されたカスタムロジックを呼び出せます。

関数セクションで、+ ボタンを選択します。
関数の一覧を見て、含める関数を選択します。

API名がない関数や、オントロジーを編集する関数は選択できません。

オントロジー SDK を生成する

エンティティを設定した後、次の手順を実行します。

選択内容を確認します。オレンジ色のインジケーターがついたエンティティには、未保存の変更があります。
OSDK を生成するを選択して、カスタムのオントロジー SDK ライブラリを作成します。
生成処理が完了するまで待ちます。
生成が完了すると、Slate の関数でオントロジー SDK を使用できるようになります。

生成タグには、アプリケーションのオントロジー SDK のバージョンが表示されます。

追加されたエンティティと、コードスニペットを含むドキュメントのサイドバーが表示されたオントロジー SDK 設定パネル。

Slate の関数でオントロジー SDK を使用する

関数エディターでは、オントロジー SDK を通じて取得したデータにアクセスし、加工できます。はじめるには、オントロジー SDK パネルで任意のエンティティを選択して、右側のパネルにドキュメントとコードスニペットを表示します。これらのスニペットは、設定に合わせて生成されており、Slate の関数に直接コピーできます。

たとえば、オブジェクトタイプを選択すると、次の内容が表示されます。

すべてのプロパティとそのAPI名およびデータ型の一覧。
単一のオブジェクトの読み込み、ページの取得、絞り込みなどのコードスニペット。
生成したオントロジー SDK に対応する正確なインポート文とメソッド呼び出し。

絞り込み、集計、アクション、その他の操作に関する詳細な構文リファレンスについては、TypeScript オントロジー SDK ガイドを参照してください。Slate はオントロジー SDK のバージョン 1 を使用し、JavaScript で記述するため、型注釈は省略されます。

pivotTo でリンクをたどる

オントロジー SDK でリンクタイプを設定した後、pivotTo メソッドを使用すると、オブジェクトセット内のすべてのオブジェクトから、リンクされたオブジェクトへリンクをたどれます。

たとえば、Dealer オブジェクトタイプから Order オブジェクトタイプへの orders リンクがある場合、ディーラーのセットに関連する注文を取得できます。

Copied!1
2
3
4
5
import { client } from "@slate/osdk";

const linkedOrders = await client.ontology.objects.Dealer
    .pivotTo("orders")
    .fetchPage({ pageSize: 30 });

代わりに単一のオブジェクトからリンクをたどるには、そのオブジェクト上のリンクに直接アクセスします。

Copied!1
2
3
4
5
import { client } from "@slate/osdk";

function getLinkedOrders(source) {
    return source.orders.fetchPageWithErrors({ pageSize: 30 });
}

pivotTo を使用するには、次の手順を実行します。

オントロジー SDK の設定にリンクタイプを含めます。
OSDK パネルでオブジェクトタイプを追加し、右下のセクションで関連するリンクを選択します。
オントロジー SDK を生成します。これで、設定したリンク名に対して pivotTo メソッドを型安全に使用できるようになります。

OSDK パネルでリンクタイプを選択すると、そのリンク用に生成されたスニペットが表示されます。スニペットには、設定に対応する正確なオブジェクトタイプとリンクのAPI名が含まれます。

オントロジー SDK の設定を管理する

エンティティのドキュメントを表示する

オントロジー SDK パネルで任意のエンティティを選択すると、右側のパネルに次の内容を含む詳細なドキュメントが表示されます。

オブジェクトタイプのプロパティ定義
アクションと関数のパラメーター仕様
選択したエンティティ用にカスタマイズされたコードスニペット

変更を確認する

オントロジー SDK パネルには、未保存の変更を示すインジケーターが表示されます。

追加されたエンティティには、生成されるまでオレンジ色のインジケーターが表示されます
削除されたエンティティには取り消し線が表示され、元に戻すオプションが付いています
変更を破棄を選択すると、最後に生成した設定に戻ります

オントロジー SDK を再生成する

オントロジー SDK を再生成する必要がある場合（たとえば、オントロジーを変更した後）は、次の手順を実行します。

OSDK を生成するの横にあるドロップダウン矢印を選択します。
最後の OSDK を再生成するを選択します。

生成ログを表示する

生成に関する問題のトラブルシューティングを行うには、次の手順を実行します。

OSDK を生成するの横にあるドロップダウン矢印を選択します。
最新の生成ログを表示を選択します。

オントロジー SDK の読み込みエラーをトラブルシューティングする

オントロジー SDK の読み込みに失敗すると、Slate はヘルスチェックダイアログにエラーを表示します。

アクションバーの問題アイコンを選択して、ヘルスチェックダイアログを開きます。
OSDK タブを選択して、詳細なエラー情報とガイダンスを表示します。
ダイアログ内の直接リンクを使用してオントロジー SDK 設定パネルを開き、問題を解決します。

ヘルスチェックダイアログの詳細については、アプリケーションをデバッグするを参照してください。

アプリケーションをインポートまたは複製する際のオントロジー SDK の動作

オントロジー SDK を使用する Slate アプリケーションをインポートまたは複製する際、オントロジー SDK バンドルの動作は次のように異なります。

アプリケーションのインポート： JSON のインポートには、オントロジー SDK バンドルは自動的に含まれません。インポート後に、OSDK を生成するドロップダウンから最後の OSDK を再生成するを選択して、バンドルを再生成する必要がある場合があります。
アプリケーションの複製： ファイルドロップダウンから名前を付けて保存… を使用すると、ソースアプリケーションから既存のオントロジー SDK バンドルがコピーされます。コピーを保存した後にオントロジー SDK の読み込みに失敗すると、Slate は SDK の再生成またはページの再読み込みを指示するツールチップを表示します。

オントロジー SDK を削除する

オントロジー SDK の設定を完全に削除するには、次の手順を実行します。

パネルのヘッダーにあるその他メニュー（3点）を選択します。
OSDK を削除するを選択します。
削除を確定します。

オントロジー SDK を削除すると、すべての設定と生成されたコードが削除されます。この操作は元に戻せません。後で必要になった場合は、オントロジー SDK を再設定する必要があります。

ベストプラクティス

小規模からはじめる： 必要なオブジェクトタイプとアクションだけを追加します。後からいつでも追加できます。
エラー処理を使用する： エラーを適切に処理するため、レスポンスのデータ型を必ず確認します。
大規模なデータセットをページ分割する： すべてのオブジェクトを一度に読み込むのではなく、適切なページサイズを指定して fetchPage() を使用します。
ドキュメントパネルを活用する： エンティティを選択して、設定に対応した最新のコードスニペットを確認します。
アプリケーションを保存する： オントロジー SDK を生成した後、Slate アプリケーションを保存して設定を保存します。