lattice-rest-integration

REST Lattice 統合の構築

プロトコルとして REST を選択した場合に、このスキルを使用します。ここでのガイダンスは、特定の言語に依存しないようにしています。可能であればユーザーが選択した言語を使い、その言語でドキュメント化された REST SDK が利用できる場合はそれを使用し、それ以外の場合は HTTP API を直接呼び出してください。

REST を選ぶ場合

ユーザーが次のことを希望する場合は、REST を優先してください。

• 最速でサンドボックスと統合したい
• 生成された protobuf スタブではなく、HTTP と JSON を使いたい
• curl、Postman、または簡単なスクリプトで手動テストしたい
• 低頻度のポーリングやリクエスト／レスポンスのワークフローを使いたい
• または Objects API を使いたい

統合でファイルのアップロード、ダウンロード、または添付が必要な場合は、Objects は REST 専用のインターフェースであることを明示し、REST のみを選択するか、REST と gRPC を組み合わせたアーキテクチャを提案してください。

ワークフロー

1. 言語を選び、あとはユーザーの選択に任せます。

   • リポジトリで既に使われている言語、またはユーザーが指定した言語を使用します。
   • その言語でドキュメント化された REST SDK がある場合は、それを優先します。
   • ない場合は、言語の変更を無理に求めず、OpenAPI インターフェースに対して生の HTTP を使用します。

2. サンドボックスに認証します。 ../lattice-sdk-integration/references/auth-and-deployment.md を使用します。

   • 認証情報は環境変数（推奨）、または統合で読み込む .env／config.yml から取得します。
   • デフォルトの認証方法は 環境トークン（ENVIRONMENT_TOKEN、有効期間の長いベアラートークン）です。要求された場合は OAuth クライアント認証情報にも対応してください。
   • サンドボックスへのリクエストには、必ずサンドボックスの認証トークンを含めてください。
   • 認証情報がない場合はユーザーに確認してください。作り上げてはいけません。

3. 正確な REST インターフェースに基づいて構築します。 正確な値は適切な情報源から取得します。フィールド名と列挙値はインストール済み SDK から取得し（イントロスペクションしてください。見つからない場合は先にインストールし、ファイルシステム検索ではなくインポートプローブを使用してください）、REST URL パスは REST OpenAPI 仕様 から取得します。 パスは SDK にはありません。生成されたクライアントではメソッドの背後に隠されているため、仕様を取得してください。

   • エンティティ：公開、取得、ポーリングまたはストリーミング、オーバーライドは Entities API を使用します。
   • タスク：Tasks API を通じて、作成、取得、ステータス更新、キャンセル、クエリ、ストリーミングを行います。
   • オブジェクト：アップロード、取得、一覧表示、メタデータには Objects API を使用します。

4. ソースデータを漏れなくマッピングします。 ../lattice-sdk-integration/references/entity-fields.md を使用します。

   • 公開前に、ソースのすべてのフィールドを洗い出します。
   • ソースから実際に情報が得られるすべてのフィールドに値を設定します。
   • チェックリストを満たすために値を捏造してはいけません。

5. 正確な値は正確に扱います。 ../lattice-sdk-integration/references/enums.md を使用します。

   • 列挙値、フィールド名、タスク仕様の URL を推測してはいけません。
   • 正確な列挙値とフィールド名は、インストール済み SDK をイントロスペクションして取得します（先に最新バージョンをインストールし、ファイルシステム検索ではなくインポートプローブで検出してください）。列挙値のスナップショット は参考用であり、最新でない場合があります。REST URL パスは REST OpenAPI 仕様 を取得してください。パスは SDK にはありません。

6. サンドボックスに対して実際に検証します。

   • 実際の統合を公開するか、実行します。
   • 別の検証ステップで、エンティティ、タスク、またはオブジェクトを読み戻します。
   • 構文チェックやローカルログだけで終わらせてはいけません。

言語に関するガイダンス

簡潔で実用的な方針にしてください。

• リポジトリに既に言語とビルドシステムがある場合は、それを使います。
• ユーザーが特定の言語を指定した場合は、その組み合わせが本当にサポートされていない場合を除き、その言語を使用します。
• ユーザーが決めかねている場合は、生の HTTP 実装を一から作るのではなく、公式にドキュメント化された REST SDK の言語を優先します。

ユーザーが明示的に求めない限り、言語の比較を長々と説明しないでください。

REST 固有のガイダンス

エンティティ

• Entities REST サーフェス経由で公開し、別途読み戻して検証してください。
• 運用上の完全性とサーバーによる受け入れを、同じくらい重要なものとして扱ってください。
• ライブエンティティには、安定した entity_id とハートビートまたは再公開の仕組みを使用してください。

タスク

• 正確なタスクタイプと正確なタスク URL を使用してください。
• タスクを実行できるエージェントでは、適切なタスク仕様 URL を提示し、ディスパッチしたタスクが終端状態に達することを確認してください。
• 実装言語が例と異なる場合でも、 ../lattice-sdk-integration/references/task-lifecycle.md に記載されているタスクのライフサイクルルールを守ってください。

オブジェクト

../lattice-sdk-integration/references/objects-api.md を使用してください。

• オブジェクトはパスでアドレス指定される BLOB です。
• アップロードだけでは不十分です。オブジェクトまたはメタデータを読み戻して検証してください。
• エンティティにメディアを添付する場合は、オブジェクトの往復とエンティティ参照の両方を検証してください。

厳守事項

• 「REST」を自動的に「Python」と同一視しないでください。
• ローカルラッパーからの 200 レベルの応答を完了の定義として扱わないでください。
• このプラグインでは、本番環境へのデプロイに関するガイダンスを使用しないでください。
• 検証後に、統合で使用した Lattice API の説明を省略しないでください。