建立資料集

建立資料集有兩個步驟：

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

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

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

必要條件

建立資料集時：

  • 顯示名稱不得與 Google Cloud 專案內的其他名稱重複。
  • 顯示名稱必須少於 64 個位元組 (因為這些字元是以 UTF-8 表示；部分語言的個別字元可用多個位元組表示)。
  • 說明不得超過 1000 個位元組。

上傳資料時：

  • 支援的檔案類型為 CSV、GeoJSON 和 KML。
  • 支援的檔案大小上限為 350 MB。
  • 屬性欄名稱的開頭不得為「?_」。
  • 系統不支援 3D 幾何圖形，包括 WKT 格式的「Z」字尾，以及 GeoJSON 格式的高度座標。

資料準備最佳做法

如果您的來源資料複雜或較大，例如密集點、長線串或多邊形 (通常超過 50 MB 的來源檔案屬於這個類別)，請考慮簡化資料 ，以在視覺化地圖上取得最佳成效。

以下是準備資料的最佳做法：

  1. 盡量減少特徵屬性。只保留需要設定樣式的地圖項目屬性 您的地圖，例如「id」和「類別」您可以將其他資源加入用戶端中的地圖項目 應用程式。舉例來說，請參閱 透過資料導向樣式即時查看資料。
  2. 盡可能在屬性物件 (例如整數) 中使用簡易資料類型， ，將地圖方塊最小化，並改善地圖效能。
  3. 在上傳檔案前簡化複雜的幾何圖形。做法是在 自選的地理空間工具，例如開放原始碼工具 Mapshaper.org 公用程式，或在 BigQuery 中使用 ST_Simplify 跨越複雜的多邊形幾何圖形
  4. 先分群非常密集的資料點，再上傳檔案。做法是在 自選的地理空間工具，例如開放原始碼工具 turf.js 叢集函式，或在 BigQuery 中 使用 ST_CLUSTERDBSCAN 基準點。

如需資料集最佳做法的其他指引，請參閱： 使用資料集和 BigQuery 以視覺化方式呈現資料。

GeoJSON 相關規定

Maps Datasets API 支援最新版 GeoJSON 規格： 也支援包含下列任一物件類型的 GeoJSON 檔案：

  • 幾何圖形物件：這種空間形狀是由一組點、線及含有自選孔洞的多邊形所組成。
  • 地圖項目物件：包含幾何圖形，以及額外的名稱/值組 (依個別應用程式而不同)。
  • 地圖項目集合：一組地圖項目物件。

Maps Datasets API 不支援含有座標參考系統資料的 GeoJSON 檔案 (CRS) WGS84。

如要進一步瞭解 GeoJSON，請參閱「符合 RFC 7946 規範」一文。

KML 相關規定

Maps Datasets API 的規定如下：

  • 所有網址都必須是檔案的本機 (或相對) 網址。
  • 支援點、線和多邊幾何圖形。
  • 所有資料屬性都視為字串。
不支援下列 KML 功能：
  • 檔案中未定義的圖示或 <styleUrl>。
  • 網路連結，例如 <NetworkLink>
  • 區域疊加層，例如 <GroundOverlay>
  • 3D 幾何圖形或所有高度相關標記，例如 <altitudeMode>
  • 相機規格，例如 <LookAt>
  • KML 檔案中定義的樣式。

CSV 相關規定

在 CSV 檔案中，支援的資料欄名稱會按照以下優先順序排列：

  • latitude、longitude
  • lat、long
  • x、y
  • wkt (Well-Known Text)
  • address、city、state、zip
  • address
  • 單一資料欄，內含所有地址資訊 (例如 1600 Amphitheatre Parkway Mountain View, CA 94043)

舉例來說，您的檔案含有名為 x、y 和 wkt 的資料欄。 由於 x 和 y 的優先順序較高 (請見上方清單中的支援資料欄名稱順序)，因此系統會使用 x 和 y 資料欄中的值，並略過 wkt 資料欄。

此外：

  • 每個資料欄名稱都必須屬於單一資料欄。也就是說，如果資料欄名為 xy 且內含 X 和 Y 座標資料，則不得使用。X 和 Y 座標必須分別位於不同的資料欄中。
  • 資料欄名稱不區分大小寫。
  • 資料欄名稱的順序沒有任何影響。舉例來說，如果您的 CSV 檔案包含 lat 和 long 資料欄，這兩欄可以按照任何順序排列。

處理資料上傳錯誤

將資料上傳至資料集時，可能會遇到本節所述的常見錯誤。

GeoJSON 錯誤

常見的 GeoJSON 錯誤包括：

  • 缺少 type 欄位，或者 type 不是字串。在上傳的 GeoJSON 資料檔案中，每個地圖項目物件和幾何圖形物件定義都必須包含名為 type 的字串欄位。

KML 錯誤

常見的 KML 錯誤包括：

  • 資料檔案不得含有上述任何不支援的 KML 功能，否則資料匯入作業可能會失敗。

CSV 錯誤

常見的 CSV 錯誤包括：

  • 部分資料列缺少幾何圖形資料欄的值。在 CSV 檔案中，幾何圖形資料欄的每一列都必須包含非空值。幾何圖形資料欄包括：
    • latitude、longitude
    • lat、long
    • x、y
    • wkt
    • address、city、state、zip
    • address
    • 單一資料欄，內含所有地址資訊 (例如 1600 Amphitheatre Parkway Mountain View, CA 94043)
  • 如果 x 和 y 是幾何圖形資料欄，請確認單位為經緯度。部分公開資料集在 x 和 y 標頭下會使用不同的座標系統。如果使用的單位有誤，則即使成功匯入資料集，算繪後的資料也可能會在非預期的位置顯示資料集點。

建立資料集

將 POST 要求傳送至 Dataset 端點：

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

傳遞 JSON 主體 傳送到定義資料集的要求中。須遵循的規定如下：

  • 指定資料集的 displayName。displayName 的值必須 而每個資料集的 ID 都不得重複

  • 將 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 或從本機檔案傳送至資料集

從 Cloud Storage 上傳資料

您可以傳送 POST 要求，從 Cloud Storage 上傳至資料集， 資料集端點 包含資料集 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 要求傳送至 資料集端點 包含資料集 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 選項指定 檔案：

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

將新資料上傳至資料集

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

您也可以將新資料上傳至資料集，建立新的資料的新版本 如要上傳新資料，請按照「上傳資料」的流程進行 從 Cloud Storage 或從檔案上傳資料， 並指定要上傳的新資料

如果新資料上傳成功：

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

  • 新版本會顯示為「有效」版本，就是您的 應用程式。

如果上傳作業發生錯誤：

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

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • 先前的資料集成功版本會維持「有效」版本，且為 因為這是應用程式所用版本