데이터 세트 만들기

데이터 세트를 만드는 과정은 두 단계로 이루어집니다.

  1. 데이터 세트 생성을 요청합니다.

  2. 데이터 세트에 데이터를 업로드하도록 요청합니다.

초기 데이터 업로드 후에는 데이터 세트에 새 데이터를 업로드하여 새 버전의 데이터 세트를 만들 수 있습니다.

데이터 세트 생성

datasets 엔드포인트에 POST 요청을 전송하여 데이터 세트를 만듭니다.

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"

응답에는 추가 정보와 함께 projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID 형식의 데이터 세트 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에서 데이터 업로드

데이터 세트의 ID도 포함된 POST 요청을 datasets 엔드포인트로 전송하여 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.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"
}

파일에서 데이터 업로드

파일의 데이터를 업로드하려면 데이터 세트의 ID도 포함된 HTTP POST 요청을 datasets 엔드포인트로 보냅니다.

https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import

요청에는 다음이 포함됩니다.

  • Goog-Upload-Protocol 헤더가 multipart로 설정됩니다.

  • 업로드할 데이터 유형을 FILE_FORMAT_GEOJSON (GeoJSON 파일), FILE_FORMAT_KML (KML 파일) 또는 FILE_FORMAT_CSV (CSV 파일)로 지정하는 파일의 경로를 지정하는 metadata 속성입니다.

    이 파일의 콘텐츠 형식은 다음과 같습니다.

    {"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 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 배열이 포함됩니다. 이 배열은 호출당 Status 유형의 오류를 최대 50개 포함하며 총 최대 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개를 초과하면(즉, 오류 페이지가 2개 이상) 응답의 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

  • 이전 데이터 세트의 성공적인 버전은 '활성' 버전으로 유지되며 앱에서 사용하는 버전입니다.