建立資料集

建立資料集的程序可分為兩個步驟：

  1. 提出建立資料集的要求。

  2. 要求將資料上傳至資料集。

首次上傳資料後，您可以將新資料上傳至資料集，建立新版資料集。

建立資料集

傳送 POST 要求至 datasets 端點，即可建立資料集：

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

將 JSON 主體傳遞至要求，定義資料集。須遵循的規定如下：

  • 指定資料集的 displayName。所有資料集的 displayName 值皆不得重複。

  • 將 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 上傳至資料集，請將 POST 要求傳送至 datasets 端點，並一併提供資料集 ID：

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

在 JSON 要求主體中：

  • 使用 inputUri 指定 Cloud Storage 中資料所屬資源的檔案路徑。這個路徑的格式為 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 要求傳送至 datasets 端點，並一併提供資料集 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"}}

  • rawdata 屬性，指定內含待上傳資料的 GeoJSON、KML 或 CSV 檔案路徑。

以下要求使用 curl -F 選項指定兩個檔案的路徑：

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 屬性會包含描述錯誤的單一訊息。不過，單一錯誤訊息不一定能提供足夠資訊，協助您找出並修正問題。

如要取得完整的錯誤資訊，請呼叫 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"

根據預設，每個頁面最多會顯示 50 個錯誤。使用 pageSize 查詢參數控管網頁大小。

將新資料上傳至資料集

建立資料集並成功上傳初始資料後，資料集的狀態會設為 STATE_COMPLETED。這表示資料集已可供應用程式使用。如要判斷資料集的 state，請參閱「取得資料集」。

你也可以將新資料上傳至資料集，建立新的資料集版本。如要上傳新資料，請按照從 Cloud Storage 上傳資料或從檔案上傳資料的相同程序操作，並指定要上傳的新資料。

如果新資料上傳成功：

  • 新版資料集的狀態會設為 STATE_COMPLETED。

  • 新版本會成為「有效」版本，並由應用程式使用。

如果上傳時發生錯誤：

  • 新版資料集的狀態會設為下列其中一種：

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • 先前的資料集成功版本會維持「有效」狀態，並做為應用程式使用的版本。