建立資料集有兩個步驟:
發出建立資料集的要求。
提出要求,將資料上傳至資料集。
初次上傳資料之後,您可以將新資料上傳至資料集,以建立新的資料集版本。
先備知識
建立資料集時:
- 顯示名稱不得與 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 的規定如下:
- 所有網址都必須是檔案的本機 (或相對) 網址。
- 支援點、線和多邊幾何圖形。
- 所有資料屬性都視為字串。
- 檔案中未定義的圖示或
<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
。
例如:
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
先前的資料集成功版本會維持在「有效」版本,且為您的應用程式使用的版本。