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

Slate でプラットフォーム SDK (PSDK) を使用する

プラットフォームソフトウェア開発キット (PSDK) を使うと、Slate 関数から Foundry API を呼び出せます。データセットのメタデータの取得、オントロジーオブジェクトの操作、その他のサポート対象のプラットフォーム API へのアクセスに使用できます。

@slate/psdk の Slate 設定済みクライアントを使用する必要があります。@osdk/foundry から操作をインポートし、クライアントを最初の引数として渡します。クライアントの作成や認証トークンの指定は不要です。リクエストには、Slate アプリケーションを実行しているユーザーの権限が使用されます。操作と引数は標準の Foundry SDK API に従いますが、Slate のサポート対象の操作による制限があります。

オントロジー SDK (OSDK) とは異なり、PSDK を使用する前にオントロジーエンティティを選択したり、ライブラリを生成したりする必要はありません。

プラットフォーム SDK を有効にする

アプリケーションで PSDK を有効にするには、次の手順を実行します。

  1. Slate アプリケーションを編集モードで開きます。
  2. 関数パネルを開き、ライブラリセクションを見つけます。
  3. Foundry SDK の横にある有効にするを選択し、SDK のバージョンが表示されるまで待ちます。

読み込まれた Foundry SDK のバージョン、使用ボタン、その他メニューが表示されたライブラリセクション。

使用を選択して最初の例をコピーし、Slate 関数に貼り付けます。

Slate 関数に @slate/psdk または @osdk/foundry からのインポートを追加した場合も、Slate によって PSDK が自動的に有効になります。SDK 設定を保存するには、アプリケーションを保存します。

PSDK には認証済みアクセスが必要であり、公開アプリケーションでは利用できません。

プラットフォーム SDK のバージョン

Slate は、アプリケーションに設定されたメジャーバージョンと一致し、かつ最小マイナーバージョンの要件を満たす、Foundry インスタンスで利用可能な最新の SDK バージョンを自動的に読み込みます。互換性のあるマイナー更新およびパッチ更新では、手動でパッケージを更新する必要はありません。

たとえば、バージョン 2.66 に設定されたアプリケーションでは、互換性のある、より新しい 2.x リリースを使用できます。Slate はアプリケーションを新しい SDK メジャーバージョンに自動的にアップグレードしません。また、メジャーバージョンの手動アップグレードはまだ利用できません。利用可能になった際は、SDK リリースノート ↗で関数の更新が必要になる可能性のある破壊的変更を確認し、アップグレード前にアプリケーションをテストしてください。

データセット名を表示する

この例では、Sales という名前のデータセットを使用します。Slate 変数にそのリソース識別子 (RID) を保持し、関数で Get Dataset API を使用して名前を取得し、テキストウィジェットに Sales を表示します。アプリケーションの各ユーザーには、データセットへのアクセス権限が必要です。

  1. 変数パネルで、データセットの RID をデフォルトの文字列値とする v_dataset_rid という名前の変数を作成します。たとえば、"ri.foundry.main.dataset.00000000-0000-0000-0000-000000000001" を入力し、サンプルの RID を実際の RID に置き換えます。

  2. 関数パネルで、f_dataset_name という名前の関数を作成し、次の JavaScript を入力します。

    Copied!
    1 2 3 4 5 import { client } from "@slate/psdk"; import { Datasets } from "@osdk/foundry"; const dataset = await Datasets.Datasets.get(client, {{v_dataset_rid}}); return dataset.name;
  3. テストを選択して関数を実行し、結果が Sales であることを確認します。

  4. テキストウィジェットを追加し、その内容を {{f_dataset_name}} に設定します。ウィジェットに Sales が表示されます。

  5. アプリケーションを保存します。

{{v_dataset_rid}} 式は、変数の現在の値を関数に渡します。同じパターンを使用して、他の Slate 変数、ウィジェットのプロパティ、関数の結果を PSDK の操作に渡すことができます。

公開 API の例を Slate 向けに調整する

Foundry API リファレンスには、操作とそのパラメーターが記載されています。そこにある TypeScript の例を Slate 向けに調整する際は、次の点に従います。

  • @osdk/foundry からの操作のインポートはそのまま保持します。
  • クライアントの作成や認証トークンの指定の代わりに、@slate/psdk から client をインポートします。接続と認証は Slate が処理します。
  • TypeScript の型注釈を含まない JavaScript を使用します。

npm パッケージをインストールしたり、SDK ライブラリを生成したりする必要はありません。例では、使用中の SDK バージョンで利用できない操作が使われている場合があるため、調整する前に Foundry SDK の横に表示されているバージョンを確認してください。詳しい背景情報については、プラットフォーム SDK の概要を参照してください。

サポート対象の操作

Slate は現在、次のパス接頭辞配下への API リクエストを許可しています。

  • オントロジーリソース:/api/v2/ontologies/
  • データセット:/api/v2/datasets/
  • 添付ファイル:/api/v2/attachments/
  • モデル:/api/v2/models/
  • 操作:/api/v2/operations/

同じリソースパスは、/api/v1/ 配下でも許可されています。操作は、使用中の SDK バージョンと Foundry インスタンスで利用可能である必要があり、必要な権限を持っている必要があります。

Admin API など、その他のエンドポイントへのリクエストは、コード補完にその操作が表示される場合でもブロックされます。

リクエストエラー

ブロックされたリクエストでは、Fetch is restricted for <URL>. と報告されます。<URL> はリクエスト先の URL です。これは、エンドポイントに接続する前に Slate がリクエストを拒否したことを意味します。

ホスト名が伏せられた、ブロックされた Admin API リクエストを示すヘルスチェックのエラーカード。

失敗した HTTP リクエストはエラーをスローします。構造化された API エラーには statusCode が含まれ、サーバーから提供される場合は errorName、errorCode、errorInstanceId、parameters も含まれます。たとえば、HTTP 404 を返すデータセットリクエストの一部のフィールドは、次のようになります。

Copied!
1 2 3 4 5 6 7 8 9 { "message": "Failed to fetch 404 Not Found", "statusCode": 404, "errorName": "DatasetNotFound", "errorCode": "NOT_FOUND", "parameters": { "datasetRid": "ri.foundry.main.dataset.00000000-0000-0000-0000-000000000001" } }

ネットワーク障害やローカルでブロックされたリクエストには、HTTP ステータスや構造化された API エラーフィールドが含まれない場合があります。関数内の try/catch でリクエストエラーを処理できます。未処理のエラーは、関数の失敗として表示されます。

テストを選択した後、未処理の HTTP 404 リクエストエラーが表示された関数プレビュー。

トラブルシューティング

  • プラットフォーム SDK の読み込みエラー:****ライブラリセクションの Foundry SDK の横にエラーアイコンが表示された場合は、アイコンにカーソルを合わせてエラーメッセージを表示します。有効化に失敗した後に有効にするが再び表示された場合は、それを選択して再試行します。
  • ブロックされたエンドポイント: API リファレンスにある操作の URL が、許可されたパス接頭辞のいずれかに一致することを確認します。コード補完に操作が表示されても、Slate がその操作を許可しているとは限りません。
  • 権限エラー: Slate アプリケーションを実行しているユーザーがリソースにアクセスでき、リクエストされた操作を実行できることを確認します。アプリケーション作成者自身にアクセス権限があっても、他のユーザーにアクセス権限が付与されるわけではありません。

失敗した関数を調べるには、関数パネルでテストを選択します。ヘルスチェックダイアログでも、失敗した関数を見つけることができます。