Veri kümesi oluştur

Veri kümesi oluşturma işlemi iki adımdan oluşur:

  1. Veri kümesini oluşturmak için istekte bulunun.

  2. Veri kümesine veri yükleme isteği gönderin.

İlk veri yükleme işleminden sonra, veri kümesinin yeni bir sürümünü oluşturmak için veri kümesine yeni veriler yükleyebilirsiniz.

Veri kümesini oluşturma

datasets uç noktasına bir POST isteği göndererek veri kümesi oluşturun:

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

Veri kümesini tanımlayan isteğe bir JSON gövdesi gönderin. Bu politika uyarınca:

  • Veri kümesinin displayName değerini belirtin. displayName değeri tüm veri kümeleri için benzersiz olmalıdır.

  • usage değerini USAGE_DATA_DRIVEN_STYLING olarak ayarlayın.

Örneğin:

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"

Yanıtta, ek bilgilerle birlikte veri kümesinin kimliği projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID biçiminde yer alır. Veri kümesini güncelleme veya değiştirme isteği gönderirken veri kümesi kimliğini kullanın.

{
  "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" 
}

Veri kümesine veri yükleme

Veri kümesini oluşturduktan sonra verileri Google Cloud Storage'dan veya yerel bir dosyadan veri kümesine yükleyin.

Yükleme işlemi eşzamansızdır. Yüklediğiniz veriler alınır ve işlenir. Yani, veri kümesinin ne zaman kullanıma hazır olacağını veya herhangi bir hata olup olmadığını belirlemek için veri kümesinin durumunu izlemek üzere bir HTTP GET isteği göndermeniz gerekir. Daha fazla bilgi için Veri işleme durumunu alma başlıklı makaleyi inceleyin.

Cloud Storage'dan veri yükleme

datasets uç noktasına veri kümesinin kimliğini de içeren bir POST isteği göndererek Cloud Storage'dan veri kümenize yükleme yaparsınız:

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

JSON istek gövdesinde:

  • Cloud Storage'da verileri içeren kaynağın dosya yolunu belirtmek için inputUri öğesini kullanın. Bu yol gs://GCS_BUCKET/FILE biçimindedir.

    İsteği gönderen kullanıcının Depolama Alanı Nesnesi Görüntüleyen rolüne veya storage.objects.get iznini içeren başka bir role sahip olması gerekir. Cloud Storage'a erişimi yönetme hakkında daha fazla bilgi için Erişim denetimine genel bakış başlıklı makaleyi inceleyin.

  • Verilerin dosya biçimini şu şekilde belirtmek için fileFormat kullanın: FILE_FORMAT_GEOJSON (GeoJson dosyası), FILE_FORMAT_KML (KML dosyası) veya FILE_FORMAT_CSV (CSV dosyası).

Örneğin:

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"

Yanıt şu şekildedir:

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

Dosyadan veri yükleme

Bir dosyadan veri yüklemek için datasets uç noktasına, veri kümesinin kimliğini de içeren bir HTTP POST isteği gönderin:

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

İstek şunları içerir:

  • Goog-Upload-Protocol üstbilgisi multipart olarak ayarlanır.

  • Yüklenecek veri türünü belirten bir dosyanın yolunu belirten metadata mülkü: FILE_FORMAT_GEOJSON (GeoJSON dosyası), FILE_FORMAT_KML (KML dosyası) veya FILE_FORMAT_CSV (CSV dosyası).

    Bu dosyanın içeriği aşağıdaki biçimdedir:

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

  • Yüklenecek verileri içeren GeoJSON, KML veya CSV dosyasının yolunu belirten rawdata mülkü.

Aşağıdaki istekte, iki dosyanın yolunu belirtmek için curl -F seçeneği kullanılmıştır:

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"

Yanıt şu şekildedir:

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

Veri işleme durumunu alma

Yükleme işlemi eşzamansızdır. Yani verileri veri kümesine yükleme API çağrısı döndükten sonra, veri beslemenin ve işlemenin başarılı olup olmadığını belirlemek için veri kümesini yoklamanız gerekir.

Veri kümesinin state değerini belirlemek için Veri kümesi alma'yı kullanın. Örneğin, veriler işlenirken state STATE_PROCESSING olarak ayarlanır. Veri kümesi uygulamanızda kullanıma hazır olduğunda state, STATE_COMPLETED olarak ayarlanır.

Örneğin, veri kümesinde GET çağrısı yapın:

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"

Başarılı bir yükleme için veri kümesinin state değeri STATE_COMPLETED olmalıdır:

{
  "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
}

Veri işleme başarısız olduğunda state, STATE_COMPLETED dışında bir değere (ör. STATE_PUBLISHING_FAILED veya _FAILED dizesiyle biten herhangi bir durum) ayarlanır.

Örneğin, bir veri kümesine veri yükler ve ardından veri kümesi ayrıntılarını almak için GET isteği gönderirsiniz. Yanıt, state mülkünün yanı sıra hatanın açıklamasını içeren tek bir errorMessage mülkü de içerir.

{
  "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
}

Veri işleme hataları alma

Veri besleme ve işleme başarısız olduğunda errorMessage mülkü, hatayı açıklayan tek bir mesaj içerir. Ancak tek bir hata mesajı, sorunları tespit edip düzeltmek için yeterli bilgi sağlamayabilir.

Hata bilgilerinin tamamını almak için fetchDatasetErrors API'sini çağırın. Bu API, bir veri kümesiyle ilişkili tüm veri işleme hatalarını döndürür:

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"

Yanıt, errors dizisini içerir. Bu dizi, arama başına Status türündeki en fazla 50 hatayı içerir ve toplamda en fazla 500 hatayı destekler:

{
  "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'den fazla hata varsa (yani birden fazla hata sayfası varsa) yanıtta nextPageToken alanında bir sayfa jetonu bulunur. Bir sonraki hata sayfasını almak için bu değeri sonraki bir çağrının pageToken sorgu parametresine iletin. nextPageToken boş olduğunda başka sayfa yoktur.

Örneğin, önceki yanıttaki jetonu kullanarak hataların bir sonraki sayfasını almak için:

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"

Varsayılan olarak yanıt, sayfa başına en fazla 50 hata içerir. Sayfa boyutunu kontrol etmek için pageSize sorgu parametresini kullanın.

Veri kümesine yeni veri yükleme

Veri kümesini oluşturduktan ve ilk verileri başarıyla yükledikten sonra veri kümesinin durumu STATE_COMPLETED olarak ayarlanır. Bu, veri kümesinin uygulamanızda kullanılmaya hazır olduğu anlamına gelir. Veri kümesinin state değerini belirlemek için Veri kümesi alma başlıklı makaleyi inceleyin.

Veri kümesinin yeni bir sürümünü oluşturmak için veri kümesine yeni veriler de yükleyebilirsiniz. Yeni veri yüklemek için Cloud Storage'dan veri yükleme veya Veriyi dosyadan yükleme'de kullandığınız işlemi uygulayın ve yüklenecek yeni verileri belirtin.

Yeni veriler başarıyla yüklenirse:

  • Veri kümesinin yeni sürümünün durumu STATE_COMPLETED olarak ayarlanır.

  • Yeni sürüm, "etkin" sürüm olur ve uygulamanız tarafından kullanılan sürümdür.

Yüklemede hata varsa:

  • Yeni veri kümesi sürümünün durumu aşağıdakilerden birine ayarlanır:

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • Önceki başarılı veri kümesi sürümü "etkin" sürüm olarak kalır ve uygulamanız tarafından kullanılan sürümdür.