데이터 세트 생성은 두 단계로 이루어집니다.
데이터 세트 만들기를 요청합니다.
데이터 세트에 데이터를 업로드하도록 요청합니다.
초기 데이터 업로드 후 데이터 세트에 새 데이터를 업로드하여 데이터 세트의 새 버전을 생성합니다
데이터 세트 생성
POST
요청을 다음으로 전송하여 데이터 세트를 만듭니다.
datasets 엔드포인트를 포함하는 것입니다.
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 사용
데이터 세트를 업데이트하거나 수정할 수 있습니다
{ "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에서 데이터 세트로 업로드합니다.
datasets 엔드포인트의
데이터 세트의 ID가 포함됩니다.
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
JSON 요청 본문:
inputUri
를 사용하여 데이터가 포함된 리소스의 파일 경로를 지정합니다. 할 수 있습니다 이 경로는 형식입니다.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" }
파일에서 데이터 업로드
파일에서 데이터를 업로드하려면 HTTP POST
요청을
datasets 엔드포인트의
에는 다음과 같이 데이터 세트의 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
입니다.
예를 들어 데이터 세트에 데이터를 업로드한 후
데이터 세트 세부정보를 가져오기 위한 요청입니다. 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
이전에 성공한 데이터 세트 버전이 '활성' 상태로 유지됩니다. 이며 앱에서 사용하는 버전