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

建立資料集

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

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

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

建立資料集

將 POST 要求傳送至 datasets 端點，即可建立資料集：

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 或本機檔案中的資料上傳至資料集。

上傳作業為非同步性質。上傳資料後，系統會擷取及處理資料。也就是說，您必須發出 HTTP GET 要求，監控資料集的狀態，以便判斷資料集何時可供使用，或是否發生任何錯誤。詳情請參閱「取得資料處理狀態」。

從 Cloud Storage 上傳資料

您可以將資料從 Cloud Storage 上傳至資料集，方法是將 POST 要求傳送至同時包含資料集 ID 的 datasets 端點：

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

取得資料處理狀態

上傳作業為非同步性質。這表示在發出 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 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
先前的資料集成功版本會維持在「有效」版本，且為您的應用程式使用的版本。