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

建立資料集

建立資料集有兩個步驟：

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

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

建立資料集

將 POST 要求傳送至 Dataset 端點：

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

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

指定資料集的 displayName。displayName 的值必須而每個資料集的 ID 都不得重複
將 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 或從本機檔案傳送至資料集

上傳作業為非同步性質。上傳資料後，系統會擷取及處理資料這表示您必須發出 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
先前的資料集成功版本會維持「有效」版本，且為因為這是應用程式所用版本