Utwórz zbiór danych

Tworzenie zbioru danych to dwuetapowy proces:

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

  2. Wyślij prośbę o przesłanie danych do zbioru danych.

Po początkowym 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 zbiorów danych:

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

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

  • określić displayName zbioru danych. Wartość displayName musi być unikalna dla wszystkich zbiorów danych.

  • ustawić 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 postaci projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID oraz dodatkowe informacje. Użyj 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 na temat sprawdzania stanu przetwarzania danych.

Przesyłanie danych z Cloud Storage

Aby przesłać dane z Cloud Storage do zbioru danych, wyślij żądanie POST do zbiorów danych punktu końcowego, 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ę do pliku zawierającego dane w Cloud Storage. Ta ścieżka ma postać gs://GCS_BUCKET/FILE.

    Użytkownik wysył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 fileFormat, aby określić format pliku danych jako: 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 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 zbiorów danych punktu końcowego, 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 ustawiony na multipart.

  • Właściwość metadata określającą ś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 ten format:

    {"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}

  • Właściwość rawdata określającą ścieżkę do pliku GeoJSON, KML lub CSV zawierającego dane do przesłania.

To żądanie używa 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"
}

Sprawdzanie stanu przetwarzania danych

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

Aby określić state zbioru danych, użyj opcji Pobierz zbiór danych. Na przykład, gdy dane są przetwarzane, state jest ustawiony na STATE_PROCESSING. Gdy zbiór danych jest gotowy do użycia w aplikacji, state jest ustawiony na STATE_COMPLETED.

Na przykład wyślij żądanie GET do 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"

W przypadku udanego przesłania 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 nie powiedzie się, state jest ustawiony na wartość inną niż STATE_COMPLETED, np. STATE_PUBLISHING_FAILED lub dowolny stan kończący się ciągiem _FAILED.

Na przykład prześlij dane do zbioru danych, a następnie wyślij żądanie GET, aby uzyskać szczegóły zbioru 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 wczytywanie i przetwarzanie danych nie powiedzie się, 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 rozwiązać problemy.

Aby uzyskać pełne informacje o błędach, wywołaj fetchDatasetErrors interfejs API. 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 Statusna 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 wystąpi więcej niż 50 błędów, czyli więcej niż 1 strona błędów, odpowiedź zawiera token strony w polu nextPageToken. Przekaż tę wartość w parametrze zapytania pageToken kolejnego wywołania, aby uzyskać następną stronę błędów. Gdy nextPageToken jest pusty, nie ma więcej 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 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ć nowe dane do zbioru danych, 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 określ nowe dane do przesłania.

Jeśli nowe dane zostaną przesłane:

  • Stan nowej wersji zbioru danych jest 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 wersją „aktywną” i jest używana przez Twoją aplikację.