このページは Cloud Translation API によって翻訳されました。

データセットの作成

データセットの作成は、次の 2 段階で行います。

データセットを作成するためのリクエストを行います。
データセットにデータをアップロードするリクエストを送信します。

最初のデータのアップロード後、データセットに新しいデータをアップロードして、データセットの新しいバージョンを作成できます。

データセットの作成

datasets エンドポイントに POST リクエストを送信してデータセットを作成します。

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

データセットを定義するリクエストに JSON 本文を渡します。以下を行ってください:

データセットの displayName を指定します。displayName の値は、すべてのデータセットで一意にする必要があります。
usage を USAGE_DATA_DRIVEN_STYLING に設定する。

注: usage でサポートされている値は USAGE_DATA_DRIVEN_STYLING のみです。

次に例を示します。

curl -X POST -d '{
    "displayName": "My Test Dataset", 
    "usage": "USAGE_DATA_DRIVEN_STYLING"
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets"

レスポンスには、データセットの ID（projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID 形式）と追加情報が含まれます。データセットの更新または変更をリクエストする場合は、データセット ID を使用します。

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "createTime": "2022-08-15T17:50:00.189682Z",
  "updateTime": "2022-08-15T17:50:00.189682Z" 
}

データセットにデータをアップロードする

データセットを作成したら、Google Cloud Storage またはローカルファイルからデータセットにデータをアップロードします。

アップロードオペレーションは非同期です。データをアップロードすると、データが取り込まれ、処理されます。つまり、HTTP GET リクエストを実行してデータセットの状態をモニタリングし、データセットが使用可能になったタイミングやエラーが発生したかどうかを判断する必要があります。詳細については、データ処理のステータスを取得するをご覧ください。

Cloud Storage からデータをアップロードする

Cloud Storage からデータセットにアップロードするには、データセットの ID も含めて datasets エンドポイントに POST リクエストを送信します。

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

JSON リクエスト本文で、次のようにします。

inputUri を使用して、Cloud Storage 内のデータを含むリソースのファイルパスを指定します。このパスは gs://GCS_BUCKET/FILE という形式です。

リクエストを行うユーザーは、storage.objects.get 権限を持つロール（Storage オブジェクト閲覧者など）を付与されている必要があります。Cloud Storage へのアクセス権の管理について詳しくは、アクセス制御の概要をご覧ください。
fileFormat を使用して、データのファイル形式を FILE_FORMAT_GEOJSON（GeoJson ファイル）、FILE_FORMAT_KML（KML ファイル）、FILE_FORMAT_CSV（CSV ファイル）のいずれかとして指定します。

次に例を示します。

curl -X POST  -d '{
    "gcs_source":{
      "inputUri": "gs://my_bucket/my_csv_file",
      "fileFormat": "FILE_FORMAT_CSV"
    }
  }' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import"

レスポンスの形式は次のとおりです。

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

ファイルからデータをアップロードする

ファイルからデータをアップロードするには、データセットの ID を含む HTTP POST リクエストを datasets エンドポイントに送信します。

https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

リクエストには以下が含まれます。

Goog-Upload-Protocol ヘッダーは multipart に設定されています。
metadata プロパティ。アップロードするデータのタイプを指定するファイルのパスを指定します。FILE_FORMAT_GEOJSON（GeoJSON ファイル）、FILE_FORMAT_KML（KML ファイル）、FILE_FORMAT_CSV（CSV ファイル）のいずれかです。

このファイルの内容は次の形式を取ります。
```
{"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
```
アップロードするデータを含む GeoJSON、KML、または CSV ファイルのパスを指定する rawdata プロパティ。

次のリクエストでは、curl -F オプションを使用して 2 つのファイルのパスを指定します。

curl -X POST \
  -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Goog-Upload-Protocol: multipart" \
  -F "metadata=@csv_metadata_file" \
  -F "rawdata=@csv_data_file" \
  "https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import"

レスポンスの形式は次のとおりです。

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

データ処理の状態を取得する

アップロードオペレーションは非同期です。つまり、データセットにデータをアップロードする API 呼び出しが返されたら、データセットをポーリングして、データの取り込みと処理が成功したかどうかを判断する必要があります。

データセットの state を確認するには、データセットを取得するを使用します。たとえば、データの処理中は、state が STATE_PROCESSING に設定されます。データセットがアプリで使用できる状態になると、state は STATE_COMPLETED に設定されます。

たとえば、データセットに対して GET 呼び出しを行います。

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46"

アップロードが正常に完了すると、データセットの state は STATE_COMPLETED になります。

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_COMPLETED",
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

データ処理に失敗すると、state は STATE_COMPLETED 以外の値（STATE_PUBLISHING_FAILED や文字列 _FAILED で終わるステータスなど）に設定されます。

たとえば、データセットにデータをアップロードしてから、GET リクエストを実行してデータセットの詳細を取得します。レスポンスには、state プロパティとともに、エラーの説明を含む単一の errorMessage プロパティも含まれます。

{
  "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46",
  "displayName": "My Test Dataset",
  "description": " ",
  "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218",
  "usage": [
    "USAGE_DATA_DRIVEN_STYLING"
  ],
  "localFileSource": {
    "filename": "Parks_Properties_20240529.csv",
    "fileFormat": "FILE_FORMAT_CSV"
  },
  "createTime": "2024-05-30T16:41:11.130816Z",
  "updateTime": "2024-05-30T16:41:14.416130Z",
  "versionCreateTime": "2024-05-30T16:41:14.416130Z",
  "status": {
    "state": "STATE_PUBLISHING_FAILED",
    "errorMessage": "INVALID_ARGUMENT: Skipping row because address could not be geocoded: 5521 18 AVENUE (from line 79)"
  },
  "sizeBytes": "6916924",
  "downloadable": true
}

データ処理エラーを取得する

データの取り込みと処理が失敗すると、errorMessage プロパティにエラーを説明する単一のメッセージが含まれます。ただし、1 つのエラーメッセージだけでは、問題を特定して修正するのに十分な情報が提供されるとは限りません。

エラーの詳細情報を取得するには、fetchDatasetErrors API を呼び出します。この API は、データセットに関連付けられているすべてのデータ処理エラーを返します。

curl -X GET \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors"

レスポンスには errors 配列が含まれます。この配列には、呼び出しごとに Status タイプのエラーを最大 50 個含めることができ、最大 500 個のエラーをサポートします。

{
  "nextPageToken": "cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj",
  "errors": [
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 631)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 457)"
    },
    {
      "code": 3,
      "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 31)"
    },
    ...
  ]
}

エラーが 50 件を超える場合（エラーのページが複数ある場合）は、レスポンスの nextPageToken フィールドにページトークンが含まれます。次の呼び出しの pageToken クエリパラメータにその値を渡して、エラーの次のページを取得します。nextPageToken が空の場合、それ以上のページはありません。

たとえば、前のレスポンスのトークンを使用してエラーの次のページを取得するには、次のコマンドを使用します。

curl -X GET \
  -H "content-type: application/json" \
  -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \
  -H "Authorization: Bearer $TOKEN" \
  "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors?pageToken=cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj"

デフォルトでは、レスポンスには 1 ページあたり最大 50 件のエラーが含まれます。ページサイズを制御するには、pageSize クエリパラメータを使用します。

データセットに新しいデータをアップロードする

データセットを作成して初期データを正常にアップロードすると、データセットの状態は STATE_COMPLETED に設定されます。つまり、データセットはアプリで使用できる状態です。データセットの state を確認するには、データセットを取得するをご覧ください。

データセットに新しいデータをアップロードして、データセットの新しいバージョンを作成することもできます。新しいデータをアップロードするには、Cloud Storage からデータをアップロードするまたはファイルからデータをアップロードすると同じプロセスを使用して、アップロードする新しいデータを指定します。

新しいデータが正常にアップロードされた場合:

新しいバージョンのデータセットの状態は STATE_COMPLETED に設定されます。
新しいバージョンが「有効な」バージョン（アプリで使用されるバージョン）になります。

アップロード中にエラーが発生した場合:

新しいデータセットバージョンの状態は、次のいずれかに設定されます。
- STATE_IMPORT_FAILED
- STATE_PROCESSING_FAILED
- STATE_PUBLISHING_FAILED
- STATE_DELETION_FAILED
以前のデータセットの成功バージョンが「有効な」バージョン（アプリで使用されるバージョン）のままになります。