建立資料集

建立資料集的程序包含兩個步驟：

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

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

必要條件

建立資料集時：

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

上傳資料時：

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

注意：上傳作業可能需要數分鐘甚至數小時才能完成，視資料檔案大小而定。如果上傳時發生錯誤，您會收到錯誤訊息。除非資料集傳回上傳作業的回應，否則請勿嘗試刪除資料集。

提示：如果資料檔案很大且有許多屬性不用設定樣式，而您想要提高算繪效能，請修改檔案，移除不需要的屬性。減少屬性數量能縮小地圖圖塊，進而改善算繪效能。

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 要求至 資料集 端點，建立資料集：

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 或本機檔案中的資料後，就無法再次將資料上傳至同一個資料集。如果上傳期間發生錯誤，您必須重新建立資料集，然後再次上傳。

從 Cloud Storage 上傳資料

如要從 Cloud Storage 將資料上傳至資料集，您可以傳送 POST 要求給也包含資料集 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

注意： 從檔案上傳資料的要求網址與從 Google Cloud Storage 上傳資料的網址不同。

要求內容包含：

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