このページは 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 つのメッセージが含まれます。ただし、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
以前のデータセットの成功バージョンが「有効な」バージョン（アプリで使用されるバージョン）のままになります。