タスク

KandaSearchのインデックス作成パイプラインはタスクによって管理されます。タスクを操作するために、外部クライアント向けの専用APIが公開されています。このAPIを使用すると、以下のことが可能です：

タスクの作成
タスクへのコマンドの実行
タスクのステータス確認

これらのAPIリクエストはすべて認証が必要です。つまり、各リクエストにはAuthorizationヘッダーに認証トークンを含める必要があります。認証の適用方法やトークンの取得方法の詳細については、KandaSearch REST API 認証を参照してください。

タスクAPIは次のベースパスを使用して公開されています：

https://api.kandasearch.com/external/v1/projects/{projectId}/instance-sets/{instanceSetId}/tasks

パス内の {projectId} および {instanceSetId} エントリは、タスクが属するプロジェクトIDとモデルインスタンスセットIDの実際の値に置き換える必要があります。これらの値は、KandaSearch管理コンソールのプロジェクトおよびモデルインスタンスセットページからコピーできます。

リクエストに対するレスポンスは、200 OK の形式で結果エンベロープとして返されます：

{
    "status": ...,
    "result": ...,
    "error": ...
}

リクエストが正常に処理された場合、レスポンスは OK の値を持つステータスと、result フィールドに結果が含まれます：

{
    "status": "OK",
    "result": {
        ...
    }
}

一方、失敗した場合は、エラーエンベロープが返されます：

{
    "status": "ERROR",
    "error": {
        "message": "command parse failed"
    }
}

タスクの作成

パイプラインでコマンドを実行する前に、最初にタスクオブジェクトを作成する必要があります。これは、以下の設定を使用してリクエストを実行することで行えます：

Method: POST
Path: https://api.kandasearch.com/external/v1/projects/{projectId}/instance-sets/{instanceSetId}/tasks
Content-Type: application/json
Body

{
    "targetId": "..."
}

targetId の値は、パイプラインの実行を処理するアプリケーションの一意の識別子を表します。この値はKandaSearchマネージャーによって提供されます。

レスポンスでは、タスクオブジェクトのデータが返されます：

{
    "status": "OK",
    "result": {
        "id": "982087df-bc98-43d3-a060-defbe09141a0",
        "projectId": "8d721283-cf1c-4985-a2ae-65c81fe5e164",
        "instanceSetId": "6b3e5dbe-5ed1-4d22-9a6b-af56cbe5a0e7",
        "targetId": "...",
        "date": "2024-05-28T21:55:14.6354669",
        "startDate": null,
        "endDate": null,
        "status": "PENDING",
        "error": null
    }
}

結果の中で最も重要な部分は、タスクの id 値です。この値は、今後のすべてのAPIリクエストで使用されます。

タスク状態の確認

現在のタスクの実行状況を確認するリクエストは以下のとおりです：

Method: GET
Path: https://api.kandasearch.com/external/v1/projects/{projectId}/instance-sets/{instanceSetId}/tasks/{taskId}
Content-Type: -
Body: -

指定された {taskId} を持つタスクオブジェクトが返されます：

{
    "status": "OK",
    "result": {
        "id": "982087df-bc98-43d3-a060-defbe09141a0",
        "projectId": "8d721283-cf1c-4985-a2ae-65c81fe5e164",
        "instanceSetId": "6b3e5dbe-5ed1-4d22-9a6b-af56cbe5a0e7",
        "targetId": "...",
        "date": "2024-05-28T21:55:14.6354669",
        "startDate": "2024-05-29T13:05:42.172919",
        "endDate": "2024-05-29T18:47:43.560023",
        "status": "COMPLETED",
        "error": null
    }
}

status が現在のタスクの状態を表します。以下の値があります。

PENDING - タスクが作成され、パイプラインで実行する準備が整っています。
RUNNING - タスクがパイプラインで実行中です。
ABORTED - タスクパイプラインが中断されました。
COMPLETED - タスクパイプラインが完了しました。
FAILED - タスクパイプラインが失敗しました。

ステータスが FAILED の場合、問題の説明は error フィールドに表示されます。startDate と endDate フィールドは、パイプラインの開始日と終了日を示します。

ステータス値 ABORTED 、COMPLETED 、および FAILED は終了状態です。その後、タスクは完了と見なされ、追加のコマンドを受け付けなくなります。

実行コマンド

タスクが作成され準備が整うと、パイプラインでコマンドが実行できます。以下のリクエストで可能です：

Method: POST
Path: https://api.kandasearch.com/external/v1/projects/{projectId}/instance-sets/{instanceSetId}/tasks/{taskId}/action
Content-Type: multipart/form-data
Body
data (application/json)

{
    "data": {
        ...
    }
}

data 部分には単一のフィールド data が含まれており、その中にアクションが指定されます。利用可能なアクションのリストとその構造はタスクによって異なります。詳細については、目的のタスクのアクションドキュメントを参照してください。

file (application/octet-stream) にはアクションに関連するファイルが含まれます。

file 部分はオプションであり、すべてのアクションがファイルを含むことを期待しているわけではありません。リクエスト内に複数の file 部分を追加することで、複数のファイルを添付することも可能です。