Tworzenie zbioru danych to proces 2-etapowy:
Wyślij żądanie utworzenia zbioru danych.
Wyślij żądanie przesłania danych do zbioru danych.
Po początkowym przesłaniu danych możesz przesłać do zbioru danych nowe dane, aby utworzyć nową wersję tego zbioru.
Tworzenie zbioru danych
Aby utworzyć zbiór danych, wyślij żądanie POST
do punktu końcowego datasets:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
Przekaż treść JSON do żądania definiującego zbiór danych. Musisz:
Podaj
displayName
zbioru danych. Wartość właściwościdisplayName
musi być niepowtarzalna we wszystkich zbiorach danych.Ustaw
usage
naUSAGE_DATA_DRIVEN_STYLING
.
Na przykład:
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"
Odpowiedź zawiera identyfikator zbioru danych w formacie projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID
oraz dodatkowe informacje. Używaj identyfikatora zbioru danych przy wysyłaniu żądań aktualizacji lub modyfikacji zbioru danych.
{ "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" }
Przesyłanie danych do zbioru danych
Po utworzeniu zbioru danych prześlij do niego dane z Google Cloud Storage lub z pliku lokalnego.
Operacja przesyłania jest asynchroniczna. Po przesłaniu danych są one przetwarzane i przetwarzane. Oznacza to, że musisz wysłać żądanie HTTP GET, aby monitorować stan zbioru danych i określić, kiedy zbiór danych jest gotowy do użycia lub czy wystąpiły błędy. Więcej informacji znajdziesz w artykule o przetwarzaniu danych.
Prześlij dane z Cloud Storage
Aby przesłać dane z Cloud Storage do zbioru danych, wysyłaj żądanie POST
do punktu końcowego datasets, które zawiera też identyfikator zbioru danych:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
W treści żądania JSON:
Użyj
inputUri
, aby określić ścieżkę pliku do zasobu zawierającego dane w Cloud Storage. Ścieżka ma formatgs://GCS_BUCKET/FILE
.Użytkownik przesyłający żądanie musi mieć rolę Storage Object Viewer lub inną rolę, która obejmuje uprawnienie
storage.objects.get
. Więcej informacji o zarządzaniu dostępem do Cloud Storage znajdziesz w artykule Omówienie kontroli dostępu.Użyj parametru
fileFormat
, aby określić format pliku danych:FILE_FORMAT_GEOJSON
(plik GeoJSON),FILE_FORMAT_KML
(plik KML) lubFILE_FORMAT_CSV
(plik CSV).
Na przykład:
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"
Odpowiedź ma taki format:
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
Przesyłanie danych z pliku
Aby przesłać dane z pliku, wyślij żądanie HTTP POST
do punktu końcowego datasets, który zawiera też identyfikator zbioru danych:
https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
Prośba zawiera:
Nagłówek
Goog-Upload-Protocol
jest ustawiony namultipart
.Właściwość
metadata
określająca ścieżkę do pliku, który określa typ danych do przesłania:FILE_FORMAT_GEOJSON
(plik GeoJSON),FILE_FORMAT_KML
(plik KML) lubFILE_FORMAT_CSV
(plik CSV).Zawartość tego pliku ma taki format:
{"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
Właściwość
rawdata
określająca ścieżkę do pliku GeoJSON, KML lub CSV zawierającego dane do przesłania.
W tym żądaniu ścieżka do 2 plików jest określona za pomocą opcji 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"
Odpowiedź ma taki format:
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
Pobranie stanu przetwarzania danych
Operacja przesyłania jest asynchroniczna. Oznacza to, że gdy wywołanie interfejsu API zwróci dane do zbioru danych, musisz przeprowadzić sondowanie zbioru danych, aby określić, czy udało się pozyskać i przetwarzać dane.
Aby określić state
zbioru danych, użyj polecenia Pobierz zbiór danych. Podczas przetwarzania danych wartość parametru state
jest ustawiona na STATE_PROCESSING
. Gdy zbiór danych będzie gotowy do użycia w aplikacji, wartość state
zostanie ustawiona na STATE_COMPLETED
.
Na przykład wywołaj metodę GET zbioru danych:
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"
Aby przesyłanie przebiegło pomyślnie, state
zbioru danych ma wartość 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 }
Gdy przetwarzanie danych się nie powiedzie, parametr state
zostanie ustawiony na wartość inną niż STATE_COMPLETED
, np. STATE_PUBLISHING_FAILED
lub dowolny stan kończący się ciągiem znaków _FAILED
.
Możesz na przykład przesłać dane do zbioru danych, a potem wysłać żądanie GET, aby uzyskać szczegóły zbioru danych. Oprócz właściwości state
odpowiedź zawiera też jedną właściwość errorMessage
z opisem błędu.
{ "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 }
Błędy przetwarzania danych
Jeśli pozyskiwanie i przetwarzanie danych nie powiedzie się, właściwość errorMessage
zawiera jeden komunikat opisujący błąd. Jednak pojedynczy komunikat o błędzie niekoniecznie zawiera wystarczające informacje do zidentyfikowania i naprawienia problemów.
Aby uzyskać pełne informacje o błędach, wywołaj interfejs API fetchDatasetErrors
. Ten interfejs API zwraca wszystkie błędy przetwarzania danych powiązane ze zbiorem danych:
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"
Odpowiedź zawiera tablicę errors
. Ta tablica zawiera maksymalnie 50 błędów typu Status
na wywołanie i obsługuje maksymalnie 500 błędów:
{ "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)" }, ... ] }
Jeśli występuje więcej niż 50 błędów, czyli więcej niż 1 stronę, odpowiedź zawiera token strony w polu nextPageToken
.
Przekaż tę wartość w parametrze zapytania pageToken
kolejnego wywołania, aby wyświetlić następną stronę błędów. Gdy nextPageToken
jest pusty, nie ma kolejnych stron.
Aby na przykład uzyskać następną stronę błędów za pomocą tokena z poprzedniej odpowiedzi:
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"
Domyślnie odpowiedź zawiera maksymalnie 50 błędów na stronę. Aby kontrolować rozmiar strony, użyj parametru zapytania pageSize
.
Przesyłanie nowych danych do zbioru danych
Po utworzeniu zbioru danych i pomyślnym przesłaniu początkowych danych stan zbioru danych jest ustawiany na STATE_COMPLETED
. Oznacza to, że zbiór danych jest gotowy do użycia w aplikacji. Aby określić state
zbioru danych, zapoznaj się z artykułem Pobieranie zbioru danych.
Możesz też przesłać nowe dane do zbioru danych, aby utworzyć jego nową wersję. Aby przesłać nowe dane, wykonaj te same czynności co w przypadku opcji Prześlij dane z Cloud Storage lub Prześlij dane z pliku i wskaż nowe dane do przesłania.
Jeśli uda się przesłać nowe dane:
Stan nowej wersji zbioru danych jest ustawiony na
STATE_COMPLETED
.Nowa wersja stanie się wersją „aktywną” i będzie używana przez aplikację.
Jeśli podczas przesyłania wystąpi błąd:
Stan nowej wersji zbioru danych jest ustawiony na jeden z tych stanów:
STATE_IMPORT_FAILED
STATE_PROCESSING_FAILED
STATE_PUBLISHING_FAILED
STATE_DELETION_FAILED
Poprzednia wersja zbioru danych, która przeszła pomyślnie testy, pozostaje „aktywną” wersją i jest używana przez aplikację.