データセットの操作¶
このページでは点群データセットを例に、Mapray Cloud API を使用したデータセットの作成・取得・更新・削除の手順を説明します。これにより、みなさまのアプリケーションから Mapray Cloud 上のデータセットを自由に操作することができるようになります。
データセットの操作には Organization Token を利用するので事前に作成しておいてください。
Organization Token の作成は「Organization Token」を、Organization Token の使い方は「API に対する認証」をご参照ください。
「Organization Token」には、各種作業を行うために必要なスコープのリストも記載されているので、行いたい操作に応じてスコープを設定するようにしてください。
データセットの作成¶
データセットの作成は、以下の手順に従って行います。
- PointCloud Dataset を作成
- Dataset の ID を用いてファイルアップロード用の URL を取得
- アップロード用の URL に 点群ファイルをアップロード
- データをコンバート
- コンバートの完了を待つ
以下でそれぞれの手順について説明します。
1. PointCloud Dataset を作成¶
初めに、PointCloud Dataset を作成します。作成には、PointCloud Dataset 作成 API を使用します。
作成時に指定する各種パラメータの詳細については、「Create PC Dataset」をご参照ください。
リクエスト例¶
最低限のパラメータを指定したリクエスト例です。
curl --request POST 'https://api.mapray.com/pcdatasets/v2/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Organization Token>' \
--data-raw '{
"name": "point cloud dataset",
"description": "my test data",
"srid": 2451,
"src_file_type": "ply",
}'
レスポンス例¶
{
"id": "5698378922983424",
"owner_id": "6252052887896064",
"created_at": "2021-08-12T02:58:27.377537Z",
"updated_at": "2021-08-12T02:58:27.377537Z",
"url": "https://api.mapray.com/pc/5698378922983424/",
"format": "raw",
"name": "point cloud dataset",
"description": "my test data",
"srid": 2451,
"status": "before_queued"
}
レスポンス内の "id" が Dataset ID となります。以降のステップで使用するので保持していおいてください。
2. Dataset の ID を用いてファイルアップロード用の URL を取得¶
1. で作成した Dataset の ID を使い、ファイルアップロード用 URL 作成 API によりアップロード用 URL を取得します。
API 仕様については「Create Upload URL」をご参照ください。
リクエスト例¶
curl --request POST 'https://api.mapray.com/pcdatasets/v2/uploads/<Dataset ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Organization Token>' \
--data-raw '[{
"filename": "sample.ply",
"size": 10000
}]'
レスポンス例¶
[
{
"filename": "sample.ply",
"url": "https://storage.googleapis.com/bucket/sample.ply?Expires=1626000000&GoogleAccessId=upload%40account&Signature=...",
"headers": {
"Content-Type": "application/octet-stream",
"x-goog-content-length-range": "10000,10000"
}
}
]
レスポンスにはアップロード用の URL と、アップロード時に指定する必要のあるヘッダのリストが含まれています。
3. アップロード用の URL に 点群ファイルをアップロード¶
2.で取得したアップロード用 URL に対してファイルをアップロードします。アップロード時は、2.のレスポンスに含まれるヘッダを一緒に指定することを忘れないでください。
NOTE: 作成したアップロード用 URL の有効期限は 30 分となっています。作成してから 30 分以内にアップロードを開始してください。一度アップロードを開始すればアップロードに 30 分以上かかっても問題ありません。
アップロードリクエスト例¶
ここでは、HTTP メソッドは PUT を使用します。
curl \
--header 'Content-Type: application/octet-stream' \
--header 'x-goog-content-length-range: 10000,10000' \
-T <file-name> <upload-url>
4. データをコンバート¶
ファイルアップロード後は Mapray JS で使用するデータ形式へのコンバート処理を、コンバート API 使って開始させます。
API 仕様については「Convert PC Dataset」をご参照ください。
リクエスト例¶
curl --request POST 'https://api.mapray.com/pcdatasets/v2/convert/<Dataset ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Organization Token>'
5. コンバートの完了を待つ¶
データセットのコンバート処理は、対象のデータの大きさによって数分から数十時間かかります。
コンバート処理が完了したかを確認するためには、データセット情報取得 API を使います。
API 仕様については「Retrieve PC Dataset」をご参照ください。
API のレスポンスに含まれるstatusパラメータがreadyとなっていれば処理が完了しています。processingの場合は変換中、errorの場合は変換に失敗したということを意味しています。
変換失敗時にはエラーメッセージがレスポンスに含まれるようになっているので参照してください。
リクエスト例¶
curl --request GET 'https://api.mapray.com/pcdatasets/v2/<Dataset ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Organization Token>'
レスポンス例¶
{
"id": "5698378922983424",
"owner_id": "6252052887896064",
"created_at": "2021-08-12T02:58:27.377537Z",
"updated_at": "2021-08-18T02:58:27.377537Z",
"url": "https://api.mapray.com/pc/5698378922983424/",
"format": "raw",
"name": "point cloud dataset",
"description": "my test data",
"srid": 2451,
"status": "ready"
}
コンバートが完了した点群データを mapray-js で描画する方法は「点群データの表示」をご参照ください。
データセット一覧の取得¶
データセットの一覧を取得するためには一覧取得 API を使用します。
クエリパラメータを使って取得するデータセット数や並び順を指定することができます。詳細は、「List PC Datasets」をご参照ください。
リクエスト例¶
curl --request GET 'https://api.mapray.com/pcdatasets/v2?page=1&limit=5' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Organization Token>'
データセット情報の更新¶
データセット情報の更新は、PATCH メソッドを利用して行います。
更新可能なパラメータは限られています。詳細については、「Update PC Dataset」をご参照ください。
また、コンバート実行中のデータセットは更新ができません。完了するまで待ってから更新を行ってください。
リクエスト例¶
curl --request PATCH 'https://api.mapray.com/pcdatasets/v2/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Organization Token>' \
--data-raw '{
"name": "new name",
"description": "new description",
}'
データセットの削除¶
データセットの削除は、DELETE メソッドを利用して行います。詳細については、「Delete PC Dataset」をご参照ください。
一度削除したデータセットは復旧させることはできないので、注意して実行してください。
また、コンバート実行中のデータセットは削除ができません。完了するまで待ってから削除を行ってください。
リクエスト例¶
curl --request DELETE 'https://api.mapray.com/pcdatasets/v2/<Dataset ID>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Organization Token>'
データセットの再作成¶
一度作成したデータセットに対して、データセット ID を変更せずに再度作り直したいというケースがあると思います。
その場合は、「Reset PC Dataset」を使用することで、データセット ID を変更せずに再作成することが可能です。
「Reset PC Dataset」を呼び出した後で、「データセットの作成」手順の2.から5.までを再度実施してください。
その他のデータセットについて¶
点群以外のデータセットの操作については、API リファレンスの各 Datasets API と、本ドキュメントサイトをご参照ください。
どのデータセットでも基本的な操作方法は同じとなっています。