Utwórz zbiór danych

Tworzenie zbioru danych to proces 2-etapowy:

  1. Wyślij żądanie utworzenia zbioru danych.

  2. 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ści displayName musi być niepowtarzalna we wszystkich zbiorach danych.

  • Ustaw usage na USAGE_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 format gs://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) lub FILE_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 na multipart.

  • 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) lub FILE_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ę.