Maps Datasets API 目前為預先發布版 (正式發布前)。正式發布前的產品和功能僅提供有限支援，且對正式發布前的產品和功能所做的變更可能與其他正式發布前的版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。

本頁面由 Cloud Translation API 翻譯而成。

建立資料集

建立資料集有兩個步驟：

發出建立資料集的要求。
提出要求，將資料上傳至資料集。

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

先備知識

建立資料集時：

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

上傳資料時：

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

資料準備最佳做法

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

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

盡量減少特徵屬性。只保留設定地圖樣式所需的地圖項目屬性，例如「id」和「category」。您可以在專屬 ID 金鑰上使用以數據為準的樣式，將額外的屬性與用戶端應用程式中的地圖項目彙整。如需範例，請參閱「使用資料導向樣式即時查看資料」一文。
盡可能在屬性物件 (例如整數) 中使用簡單的資料類型，以便盡可能縮小圖塊大小並提高地圖效能。
在上傳檔案前簡化複雜的幾何圖形。您可以在自選的地理空間工具中執行這項操作，例如開放原始碼 Mapshaper.org 公用程式，或在 BigQuery 中使用 ST_Simplify 對複雜的多邊形幾何圖形。
先分群非常密集的資料點，再上傳檔案。您可以在自選的地理空間工具中執行這項操作，例如開放原始碼 turf.js 叢集函式，或是在 BigQuery 中針對密集點幾何圖形使用 ST_CLUSTERDBSCAN。

如要進一步瞭解資料集最佳做法，請參閱使用資料集和 BigQuery 以視覺化方式呈現資料一文。

GeoJSON 相關規定

Maps Datasets API 支援目前的 GeoJSON 規格，也支援包含下列任一物件類型的 GeoJSON 檔案：

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

除了 WGS84 以外，Maps Datasets API 不支援含有其他座標參考系統 (CRS) 資料的 GeoJSON 檔案。

如要進一步瞭解 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 值不得重複。
將 usage 設為 USAGE_DATA_DRIVEN_STYLING。

注意： USAGE_DATA_DRIVEN_STYLING 是 usage 支援的唯一值。

例如：

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 要求到包含資料集 ID 的資料集端點，從 Cloud Storage 上傳至資料集：

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

將新資料上傳至資料集

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

您還可以將新資料上傳至資料集，建立新的資料集版本。如要上傳新資料，請使用與從 Cloud Storage 上傳資料或從檔案上傳資料相同的程序，然後指定要上傳的新資料。

如果新資料上傳成功：

新版資料集的狀態會設為 STATE_COMPLETED。
新版本會變成「有效」版本，也就是應用程式採用的版本。

如果上傳作業發生錯誤：

新資料集版本的狀態會設為下列其中一種狀態：
- STATE_IMPORT_FAILED
- STATE_PROCESSING_FAILED
- STATE_PUBLISHING_FAILED
- STATE_DELETION_FAILED
先前的資料集成功版本會維持在「有效」版本，且為您的應用程式使用的版本。