Utwórz zbiór danych

Tworzenie zbioru danych to proces dwuetapowy:

  1. Prześlij prośbę o utworzenie zbioru danych.

  2. wysłać prośbę o przesłanie danych do zbioru danych;

Po pierwszym przesłaniu danych możesz przesłać nowe dane do zbioru danych, aby utworzyć jego nową wersję.

Tworzenie zbioru danych

Utwórz zbiór danych, wysyłając żądanie POST do punktu końcowego datasets:

https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets

Przekaż do żądania treść JSON określającą zbiór danych. Musisz:

  • Określ displayName zbioru danych. Wartość displayName musi być niepowtarzalna we wszystkich zbiorach danych.

  • Ustaw wartość 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 podczas wysyłania żą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 dane są wczytywane i przetwarzane. Oznacza to, że musisz wysłać żądanie HTTP GET, aby monitorować stan zbioru danych i sprawdzić, kiedy będzie on gotowy do użycia lub czy wystąpiły jakieś błędy. Więcej informacji znajdziesz w artykule Pobieranie stanu przetwarzania danych.

Przesyłanie danych z Cloud Storage

Aby przesłać dane z Cloud Storage do zbioru danych, wyślij żą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 w formacie 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 wysyłający żądanie musi mieć rolę Przeglądający obiekt pamięci 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 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 postać:

{
  "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óre zawiera też identyfikator zbioru danych:

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

Żądanie zawiera:

  • Nagłówek Goog-Upload-Protocol ma wartość multipart.

  • Właściwość metadata określająca ścieżkę do pliku, który określa typ przesyłanych danych jako: 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 użyto opcji curl -F, aby określić ścieżkę do 2 plików:

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 postać:

{
  "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER"
}

Pobieranie stanu przetwarzania danych

Operacja przesyłania jest asynchroniczna. Oznacza to, że po wywołaniu interfejsu API w celu przesłania danych do zbioru danych musisz sprawdzić, czy wczytywanie i przetwarzanie danych zakończyło się powodzeniem, czy nie.

Aby określić state zbioru danych, użyj funkcji Pobierz zbiór danych. Na przykład podczas przetwarzania danych wartość state jest ustawiona na STATE_PROCESSING. Gdy zbiór danych będzie gotowy do użycia w aplikacji, ikona state zmieni się na STATE_COMPLETED.

Na przykład wywołaj GET na zbiorze 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 przesłanie się powiodło, state zbioru danych musi być 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, wartość parametru state jest ustawiana 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ółowe informacje o zbiorze danych. Oprócz właściwości state odpowiedź zawiera też pojedynczą 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
}

Pobieranie błędów przetwarzania danych

Gdy przesyłanie i przetwarzanie danych się nie powiedzie, właściwość errorMessage zawiera pojedynczy komunikat opisujący błąd. Jednak pojedynczy komunikat o błędzie nie zawsze zawiera wystarczające informacje, aby zidentyfikować i naprawić problemy.

Aby uzyskać pełne informacje o błędzie, 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 łącznie do 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 błędów jest więcej niż 50, czyli więcej niż 1 strona błędów, odpowiedź zawiera token strony w polu nextPageToken. Przekaż tę wartość w parametrze zapytania pageToken w kolejnym wywołaniu, aby uzyskać następną stronę błędów. Gdy pole nextPageToken jest puste, nie ma więcej stron.

Aby na przykład pobrać 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 przesłaniu początkowych danych stan zbioru danych zostanie ustawiony na STATE_COMPLETED. Oznacza to, że zbiór danych jest gotowy do użycia w aplikacji. Aby określić state zbioru danych, zobacz Pobieranie zbioru danych.

Możesz też przesłać do zbioru danych nowe dane, aby utworzyć jego nową wersję. Aby przesłać nowe dane, wykonaj te same czynności, co w przypadku przesyłania danych z Cloud Storage lub przesyłania danych z pliku, i wskaż nowe dane do przesłania.

Jeśli nowe dane zostaną przesłane:

  • Stan nowej wersji zbioru danych zostanie ustawiony na STATE_COMPLETED.

  • Nowa wersja staje się wersją „aktywną” i jest używana przez Twoją 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 pozostaje „aktywną” wersją i jest używana przez aplikację.