データセットの作成

データセットは、次の 2 段階のプロセスで作成します。

  1. データセットの作成をリクエストします。

  2. データセットへのデータのアップロードをリクエストします。

最初のデータのアップロード後、データセットに新しいデータをアップロードし、 変更します。

データセットの作成

POST リクエストを datasets エンドポイント:

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

JSON 本文を渡す データセットを定義する必要があります。以下を行ってください:

  • データセットの displayName を指定します。displayName の値は、 一意である必要があります。

  • usageUSAGE_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" 
}

データセットへのデータのアップロード

データセットを作成したら、Cloud Storage から Google Cloud Storage ローカル ファイルからデータセットにエクスポートできます。

アップロード操作は非同期です。データをアップロードすると、そのデータは 表示されます。つまり、HTTP GET リクエストを実行して 状態を使用して、データセットが使用可能になったか、 エラーが発生しました。詳細については、データ処理を取得する 確認します

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

Cloud Storage からデータセットにアップロードするには、POST リクエストを データセット エンドポイントを には、データセットの ID が含まれます。

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

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

  • inputUri を使用して、データを含むリソースのファイルパスを指定します。 作成されます。このパスの形式は次のとおりです。 gs://GCS_BUCKET/FILE

    リクエストを行うユーザーには、Storage オブジェクトが必要です。 閲覧者 ロール、または storage.objects.get 権限を含むその他のロール。対象 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"
}

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

ファイルからデータをアップロードするには、HTTP POST リクエストを データセット エンドポイントを には、データセットの ID が含まれています。

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 を判別するには、 [Get a dataset] を使用します。たとえば、データが正規化されている間、 処理されると、stateSTATE_PROCESSING に設定されます。データセットの準備ができたら stateSTATE_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"

アップロードが成功した場合、データセットの stateSTATE_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
}

データ処理が失敗した場合、stateSTATE_COMPLETEDSTATE_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 配列が含まれます。この配列には、次のエラーが最大 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 を特定するには、 データセットをご覧ください。

新しいデータをデータセットにアップロードして、データの新しいバージョンを 見てみましょう。新しいデータをアップロードする際は、データのアップロードと同じ手順で操作します。 またはファイルからデータをアップロード、 アップロードする新しいデータを指定します。

新しいデータが正常にアップロードされると、次のようになります。

  • データセットの新しいバージョンの状態は STATE_COMPLETED に設定されます。

  • 新しいバージョンは「アクティブ」Pod で使用されるバージョンです。 。

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

  • 新しいデータセットのバージョンの状態は、次のいずれかの状態に設定されます。

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED
  • 前のデータセットの成功バージョンは「アクティブ」のままであり、 アプリが使用しているバージョン。