このページは 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"

レスポンスには、projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID 形式のデータセットの 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 も含む POST リクエストを datasets エンドポイントに送信します。

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 配列が含まれます。この配列には、呼び出しごとに最大 50 個の Status 型のエラーが含まれ、合計で最大 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
以前のデータセットの成功バージョンが「有効な」バージョン（アプリで使用されるバージョン）のままになります。

データセットの作成 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

データセットの作成

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

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

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

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

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

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

データセットの作成