Veri kümesi oluşturma

Veri kümesi oluşturma iki adımlı bir işlemdir:

  1. Veri kümesini oluşturma isteğinde bulunun.

  2. Veri kümesine veri yükleme isteğinde bulunun.

İ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.

Ön koşullar

Veri kümesi oluştururken:

  • Görünen adlar, Google Cloud projenizde benzersiz olmalıdır.
  • Görünen adlar 64 bayttan küçük olmalıdır (Bu karakterler UTF-8'de temsil edildiği için bazı dillerde her karakter birden fazla baytla temsil edilebilir).
  • Açıklamalar 1.000 bayttan küçük olmalıdır.

Veri yüklerken:

  • Desteklenen dosya türleri CSV, GeoJSON ve KML'dir.
  • Desteklenen maksimum dosya boyutu 350 MB'tır.
  • Özellik sütunu adları "?_" dizesiyle başlayamaz.
  • Üç boyutlu geometriler desteklenmez. Buna, WKT biçimindeki "Z" son eki ve GeoJSON biçimindeki rakım koordinatı dahildir.

Veri hazırlamayla ilgili en iyi uygulamalar

Yoğun noktalar, uzun çizgi dizeleri veya poligonlar (genellikle 50 MB'tan büyük kaynak dosya boyutları bu kategoriye girer) gibi kaynak verileriniz karmaşık veya büyükse görsel bir haritada en iyi performansı elde etmek için yükleme işleminden önce verilerinizi basitleştirmeyi düşünün.

Verilerinizi hazırlamaya yönelik en iyi uygulamalardan bazıları şunlardır:

  1. Özellik özelliklerini en aza indirin. Yalnızca haritanızın stilini belirlemek için gerekli olan "id" ve "category" gibi özellik özelliklerini koruyun. Benzersiz tanımlayıcı anahtarında veriye dayalı stilleri kullanarak istemci uygulamasındaki bir özelliğe ek özellikler ekleyebilirsiniz. Örneğin, Veriye dayalı stil ile verilerinizi gerçek zamanlı olarak görme konusuna bakın.
  2. Karo boyutunu en aza indirmek ve harita performansını iyileştirmek amacıyla, mümkün olduğunda tamsayı gibi mülk nesneleri için basit veri türlerini kullanın.
  3. Bir dosya yüklemeden önce karmaşık geometrileri basitleştirin. Bu işlemi, açık kaynaklı Mapshaper.org yardımcı programı gibi istediğiniz bir coğrafi araçta veya karmaşık poligon geometrileri üzerinde ST_Simplify kullanarak BigQuery'de yapabilirsiniz.
  4. Bir dosya yüklemeden önce çok yoğun noktaları kümeleyin. Bu işlemi açık kaynaklı turf.js küme işlevleri gibi istediğiniz coğrafi bir araçta veya yoğun nokta geometrileri üzerinde ST_CLUSTERDBSCAN kullanarak BigQuery'de yapabilirsiniz.

Veri kümeleri ve BigQuery ile verilerinizi görselleştirme bölümünde, veri kümeleriyle ilgili en iyi uygulamalar hakkında daha fazla bilgi bulabilirsiniz.

GeoJSON gereksinimleri

Maps Datasets API, mevcut GeoJSON spesifikasyonunu destekler. Maps Datasets API, aşağıdaki nesne türlerinden herhangi birini içeren GeoJSON dosyalarını da destekler:

  • Geometri nesneleri. Geometri nesnesi, noktaların, çizgilerin ve poligonların isteğe bağlı deliklerle birleşimi olarak tanımlanan mekansal bir şekildir.
  • Nesneleri öne çıkarın. Özellik nesnesi, bir geometri ve ek ad/değer çiftleri içerir. Bu çiftlerin anlamı, uygulamaya özgüdür.
  • Özellik koleksiyonları. Özellik koleksiyonu, özellik nesnelerinden oluşan bir gruptur.

Maps Datasets API, WGS84 dışında bir koordinat referans sisteminde (CRS) verileri olan GeoJSON dosyalarını desteklemez.

GeoJSON hakkında daha fazla bilgi için RFC 7946 uyumlu bölümüne bakın.

KML gereksinimleri

Haritalar Veri Kümeleri API'si aşağıdaki şartlara sahiptir:

  • Tüm URL'ler, dosyanın kendisinde yerel (veya göreli) olmalıdır.
  • Nokta, çizgi ve poligon geometrileri desteklenir.
  • Tüm veri özellikleri dize olarak kabul edilir.
Aşağıdaki KML özellikleri desteklenmez:
  • Dosyanın dışında tanımlanmış simgeler veya <styleUrl>.
  • Ağ bağlantıları, ör. <NetworkLink>
  • <GroundOverlay> gibi zemin bindirmeler
  • 3D geometriler veya <altitudeMode> gibi rakımla ilgili etiketler
  • Kamera özellikleri (ör. <LookAt>)
  • KML dosyasında tanımlanan stiller.

CSV koşulları

CSV dosyaları için, desteklenen sütun adları öncelik sırasına göre aşağıda listelenmiştir:

  • latitude, longitude
  • lat, long
  • x, y
  • wkt (İyi Bilinen Metin)
  • address, city, state, zip
  • address
  • Tüm adres bilgilerini içeren tek bir sütun (ör. 1600 Amphitheatre Parkway Mountain View, CA 94043)

Örneğin, dosyanız x, y ve wkt adlı sütunlar içeriyor. Yukarıdaki listede yer alan desteklenen sütun adlarının sırasına göre belirlendiği üzere x ve y daha yüksek önceliğe sahip olduğu için x ve y sütunlarındaki değerler kullanılır ve wkt sütunu yoksayılır.

Ayrıca:

  • Her sütun adı tek bir sütuna ait olmalıdır. Yani hem x hem de y koordinat verilerini içeren xy adlı bir sütununuz olamaz. x ve y koordinatları ayrı sütunlarda yer almalıdır.
  • Sütun adları büyük/küçük harfe duyarlı değildir.
  • Sütun adlarının sırası önemli değildir. Örneğin, CSV dosyanız lat ve long sütunları içeriyorsa bunlar herhangi bir sırada olabilir.

Veri yükleme hatalarını işleme

Bir veri kümesine veri yüklerken bu bölümde açıklanan yaygın hatalardan biriyle karşılaşabilirsiniz.

GeoJSON hataları

Yaygın GeoJSON hataları şunlardır:

  • type alanı eksik veya type bir dize değil. Yüklenen GeoJSON veri dosyası, her bir özellik nesnesi ve Geometri nesne tanımının parçası olarak type adlı bir dize alanı içermelidir.

KML hataları

Yaygın KML hataları şunlardır:

  • Veri dosyası, yukarıda listelenen desteklenmeyen KML özelliklerinden hiçbirini içermemelidir. Aksi takdirde, verileri içe aktarma işlemi başarısız olabilir.

CSV hataları

Sık karşılaşılan CSV hataları şunlardır:

  • Bazı satırlarda bir geometri sütunu için değer eksik. Bir CSV dosyasındaki tüm satırlar, geometri sütunları için boş olmayan değerler içermelidir. Geometri sütunları şunları içerir:
    • latitude, longitude
    • lat, long
    • x, y
    • wkt
    • address, city, state, zip
    • address
    • Tüm adres bilgilerini içeren tek bir sütun (ör. 1600 Amphitheatre Parkway Mountain View, CA 94043)
  • Geometri sütunlarınız x ve y ise birimlerin boylam ve enlem biçiminde olduğundan emin olun. Bazı herkese açık veri kümeleri, x ve y başlıkları altında farklı koordinat sistemleri kullanır. Yanlış birimler kullanılırsa veri kümesi başarıyla içe aktarılabilir ancak oluşturulan veriler beklenmedik konumlardaki veri kümesi noktalarını gösterebilir.

Veri kümesini oluşturma

Veri kümeleri uç noktasına POST isteği göndererek bir 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 iletin. Bu politika uyarınca:

  • Veri kümesinin displayName öğesini 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ıt, veri kümesinin kimliğini projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID biçiminde ve ek bilgilerle birlikte içerir. Veri kümesini güncelleme veya değiştirme isteğinde bulunurken 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.

Cloud Storage'dan veri yükleme

Veri kümesinin kimliğini de içeren veri kümeleri uç noktasına 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'daki verileri içeren kaynağın dosya yolunu belirtmek için inputUri öğesini kullanın. Bu yol gs://GCS_BUCKET/FILE biçimindedir.

    İsteği yapan kullanıcının Depolama Alanı Nesne Görüntüleyici rolüne veya storage.objects.get iznini içeren başka bir role ihtiyacı vardır. Cloud Storage'a erişimi yönetme hakkında daha fazla bilgi için Erişim denetimine genel bakış sayfasını 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 biçimdedir:

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

Dosyadan veri yükleme

Bir dosyadan veri yüklemek için veri kümeleri 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çeriyor:

  • Goog-Upload-Protocol başlığı multipart olarak ayarlandı.

  • Yüklenecek verilerin türünü belirten bir dosyanın yolunu belirten metadata özelliği: 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 özelliği.

Aşağıdaki istekte, iki dosyanın yolunu belirtmek için curl -F seçeneği kullanılmaktadı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 biçimdedir:

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

Veri kümesine yeni veri yükleme

Veri kümesini oluşturup 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 bölümüne bakın.

Ayrıca, veri kümesinin yeni bir sürümünü oluşturmak için veri kümesine yeni veriler yükleyebilirsiniz. Yeni veri yüklemek için Cloud Storage'dan veri yükleme veya Dosyadan veri yükleme için yaptığınız işlemin aynısını 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ükleme işleminde hata varsa:

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

    • STATE_IMPORT_FAILED
    • STATE_PROCESSING_FAILED
    • STATE_PUBLISHING_FAILED
    • STATE_DELETION_FAILED

  • Önceki veri kümesinin başarılı sürümü, "etkin" sürüm olarak kalır ve uygulamanızın kullandığı sürümdür.