建立資料集有兩個步驟:
發出建立資料集的要求。
提出要求,將資料上傳至資料集。
初次上傳資料之後,您可以將新資料上傳至資料集以建立 新版資料集
建立資料集
將 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 或從本機檔案傳送至資料集
上傳作業為非同步性質。上傳資料後,系統會 擷取及處理資料這表示您必須發出 HTTP GET 要求來監控 用來判斷資料集何時可供使用,或 發生任何錯誤。詳情請參閱取得資料處理資料 狀態。
從 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" }
取得資料處理狀態
上傳作業為非同步性質。這表示在 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
敬上
也能使用 Google Cloud CLI 或
Compute Engine 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
先前的資料集成功版本會維持「有效」版本,且為 因為這是應用程式所用版本