Hızlı Başlangıç: Azure Cosmos DB SQL API verilerini yönetmek için Spring Data Azure Cosmos DB v3 uygulaması derleme

UYGULANDıĞı YER: SQL API

Bu hızlı başlangıçta, Azure portal'den bir Azure Cosmos DB SQL API hesabı oluşturur ve yönetirsiniz ve Azure portal'den kopyalanan Spring Data Azure Cosmos DB v3 uygulamasını GitHub. İlk olarak, Azure portal kullanarak bir Azure Cosmos DB SQL API hesabı oluşturun, sonra Spring Data Azure Cosmos DB v3 bağlayıcısını kullanarak bir Spring Boot uygulaması oluşturun ve Cosmos DB hesabınıza kaynakları Spring Boot ekleyin. Azure Cosmos DB, genel dağıtım ve yatay ölçeklendirme özellikleriyle belge, tablo, anahtar-değer ve graf veritabanlarını hızlı bir şekilde oluşturmanızı ve sorgulamanızı sağlayan çok modelli bir veritabanı hizmetidir.

Önemli

Bu sürüm notları Spring Data Azure Cosmos DB'nin 3. sürümüne göredir. Sürüm 2'nin sürüm notlarını burada bulabilirsiniz.

Spring Data Azure Cosmos DB yalnızca SQL API'sini destekler.

Diğer Azure Cosmos DB API'leri üzerinde Spring Data hakkında bilgi için şu makalelere bakın:

Önkoşullar

Giriş notları

Cosmos DB hesabının yapısı. API veya programlama dilinden bağımsız olarak, Cosmos DB hesabı sıfır veya daha fazla veritabanı içerir, veritabanı (DB) sıfır veya daha fazla kapsayıcı içerir ve kapsayıcı aşağıdaki diyagramda gösterildiği gibi sıfır veya daha fazla öğe içerir:

Azure Cosmos hesabı varlıkları

Veritabanları, kapsayıcılar ve öğeler hakkında daha fazla bilgi için buraya bakabilirsiniz. Sağlanan aktarım hızı ve bölüm anahtarı arasında kapsayıcı düzeyinde birkaç önemli özellik tanımlanır.

Sağlanan aktarım hızı, parasal fiyatıolan ve hesabın işletim maliyetinde önemli bir belirleyici faktör olan İstek Birimleri (RU) ile ölçülür. Sağlanan aktarım hızı kapsayıcı başına ayrıntı düzeyinde veya veritabanı başına ayrıntı düzeyinde seçilebilir, ancak kapsayıcı düzeyi aktarım hızı belirtimi genellikle tercih edilir. Aktarım hızı sağlama hakkında daha fazla bilgi için buraya bakebilirsiniz.

Öğeler bir veritabanı veritabanı kapsayıcı Cosmos veritabanı, istekleri işlemek için daha fazla depolama ve işlem ekleyerek yatay olarak büyür. Depolama ve işlem kapasitesi bölümler olarak bilinen ayrık birimlere eklenir ve belgelerinizin bir alanını bölüm anahtarı olarak seçmeniz ve her belgeyi bir bölümle eşler. Bölümlerin yönetilma yolu, her bölüme bölüm anahtarı değerleri aralığından kabaca eşit bir dilim atanmış olmasıdır; bu nedenle, görece rastgele veya eşit dağıtılmış bir bölüm anahtarı seçmeniz önerilir. Aksi takdirde, bazı bölümler önemli ölçüde daha fazla istek (sık bölüm) görebilirken, diğer bölümler çok daha az istek(durulmuş bölüm) görüyor ve bu durumdan kaçınılması gerekir. Bölümleme hakkında daha fazla bilgi için buraya bakebilirsiniz.

Veritabanı hesabı oluşturma

Bir belge veritabanı oluşturmadan önce Azure Cosmos DB ile bir SQL API hesabı oluşturmanız gerekir.

  1. Kaynak Azure portal veya Giriş sayfasında Kaynak oluştur'a tıklayın.

  2. Yeni sayfasında Azure veritabanı için arama Cosmos seçin.

  3. Azure veritabanı Cosmos Oluştur'a tıklayın.

  4. Azure Cosmos DB Hesabı Oluştur sayfasında, yeni Azure veritabanı hesabı için temel Cosmos girin.

    Ayar Değer Açıklama
    Abonelik Abonelik adı Bu Azure Cosmos hesabı için kullanmak istediğiniz Azure aboneliğini seçin.
    Kaynak Grubu Kaynak grubu adı Bir kaynak grubu seçin veya Yeni oluştur seçeneğini belirleyin ve yeni kaynak grubu için benzersiz bir ad girin.
    Hesap Adı Benzersiz bir ad Azure Cosmos hesabınızı tanımlayan bir ad girin. URI’nizi oluşturmak için sağladığınız ada documents.azure.com ekleneceği için benzersiz bir ad kullanın.

    Ad yalnızca küçük harf, sayı ve kısa çizgi (-) karakterini içerebilir. 3-44 karakter uzunluğunda olmalıdır.
    API Oluşturulacak hesap türü SQL söz dizimini kullanarak belge veritabanı ve sorgusu oluşturmak için Cekirdek (SQL) seçeneğini belirleyin.

    API, oluşturulacak hesap türünü belirler. Azure Cosmos DB beş API sağlar: Belge verileri için Çekirdek (SQL) ve MongoDB, graf verileri için Gremlin, Azure Tablosu ve Cassandra. Şu anda, her API için farklı bir hesap oluşturmanız gerekir.

    SQL API’si hakkında daha fazla bilgi edinin.
    Konum Kullanıcılarınıza en yakın bölge Azure Cosmos DB hesabınızın barındırılacağı coğrafi konumu seçin. Verilere en hızlı erişimi sağlamak için kullanıcılarınıza en yakın olan konumu kullanın.
    Kapasite modu Sağlanan aktarım hızı veya Sunucusuz Sağlanan aktarım hızı modunda bir hesap oluşturmak için Sağlanan aktarım hızı'ı seçin. Sunucusuz modda bir hesap oluşturmak için Sunucusuz'ı seçin.
    Azure Cosmos DB ücretsiz katmanı indirimini uygulama Uygula veya Uygula Azure Cosmos DB ücretsiz katmanı ile bir hesapta ilk 1000 RU/sn ve 25 GB depolama alanı ücretsiz olarak elde edilir. Ücretsiz katman hakkında daha fazla bilgi.

    Not

    Azure aboneliği başına en fazla bir ücretsiz katman azure Cosmos DB hesabınız olabilir ve hesabı oluştururken kabul etmek zorundasınız. Ücretsiz katman indirimi uygulama seçeneğini görmüyorsanız, bu abonelikte başka bir hesabın ücretsiz katmanla zaten etkinleştirilmiştir.

    Azure Cosmos DB için yeni hesap sayfası

  5. Genel Dağıtım sekmesinde aşağıdaki ayrıntıları yapılandırabilirsiniz. Bu hızlı başlangıç için varsayılan değerleri bırakın:

    Ayar Değer Açıklama
    Coğrafi Yedeklilik Devre Dışı Bırak Bölgenizi bir çift bölgeyle eşleştirerek hesabınız üzerinde genel dağıtımı etkinleştirin veya devre dışı bırakma. Hesabınıza daha sonra daha fazla bölge ekebilirsiniz.
    Birden Çok Bölgeli Yazmalar Devre Dışı Bırak Çok bölgeli yazma özelliği, dünya genelindeki veritabanlarınız ve kapsayıcılar için sağlanan aktarım hızından yararlanmanızı sağlar.

    Not

    Kapasite modu olarak Sunucusuz seçeneğini belirtirsanız aşağıdaki seçenekler kullanılamaz:

    • Ücretsiz Katman İndirimi Uygula
    • Coğrafi yedeklilik
    • Birden Çok Bölgeli Yazmalar
  6. İsteğe bağlı olarak, aşağıdaki sekmelerde ek ayrıntıları yapılandırabilirsiniz:

    • - Sanal ağdan erişimi yapılandırma.
    • Yedekleme İlkesi - Düzenli veya sürekli yedekleme ilkesi yapılandırma.
    • Şifreleme - Hizmet tarafından yönetilen anahtarı veya müşteri tarafından yönetilen anahtarı kullanın.
    • Etiketler- Etiketler, kaynakları kategorilere ayırmayı ve aynı etiketi birden çok kaynağa ve kaynak gruplarına uygulayarak birleştirilmiş faturalamayı görüntülemenizi sağlayan ad/değer çiftleridir.
  7. Gözden geçir ve oluştur’u seçin.

  8. Hesap ayarlarını gözden geçirip Oluştur seçeneğini belirleyin. Hesabın oluşturulması birkaç dakika sürer. Portal sayfasında Dağıtımınız tamamlandı iletisinin görüntülenmesini bekleyin.

    Azure portaldaki Bildirimler bölmesi

  9. Azure Cosmos DB hesabı sayfasına gitmek için Kaynağa git seçeneğini belirleyin.

    Azure Cosmos DB hesabı sayfası

Kapsayıcı ekleme

Artık veritabanı ve kapsayıcı Veri Gezgini için Azure portal aracı kullanabilirsiniz.

  1. Yeni > Veri Gezgini'ı seçin.

    Kapsayıcı Ekle alanı en sağda görüntülenir, görmek için sağa kaydırmanız gerekir.

    Azure portalındaki Veri Gezgini, Kapsayıcı Ekle bölmesi

  2. Kapsayıcı ekle sayfasında yeni kapsayıcının ayarlarını girin.

    Ayar Önerilen değer Açıklama
    Veritabanı Kimliği ToDoList Yeni veritabanınızın adı olarak Görevler girin. Veritabanı adları 1 ile 255 karakter arasında olmalı ve , veya /, \\, #, ? sonda boşluk içeremez. Aktarım hızını kapsayıcılar arasında paylaş seçeneğini işaretleyin. Bu seçenek, veritabanında sağlanan aktarım hızını veritabanındaki tüm kapsayıcılar arasında paylaşmaya olanak sağlar. Bu seçenek, maliyet tasarrufları için de yardımcı olur.
    Veritabanı aktarım hızı Otomatik Ölçeklendirme veya El ile aktarım hızı s sağlanmasını sebilirsiniz. El ile aktarım hızı RU/sn'leri kendiniz ölçeklendirmeye olanak sağlarken, otomatik ölçeklendirme aktarım hızı sistemin RU/sn'leri kullanıma göre ölçeklendirmelerine olanak sağlar. Bu örnek için El ile'yi seçin.

    Aktarım hızını saniye başına 400 istek birimi (RU/sn) olarak bırakın. Gecikme süresini azaltmak için, kapasite hesaplayıcısı ile gerekli RU/sn'leri tahmin ederek aktarım hızının ölçeğini artırabilirsiniz.

    Not: Bu ayar, sunucusuz bir hesapta yeni bir kapsayıcı oluşturulurken kullanılamaz.
    Kapsayıcı Kimliği Öğeler Yeni kapsayıcınız için öğe adını girin. Kapsayıcı kimliklerinin karakter gereksinimleri, veritabanı adlarına ilişkin karakter gereksinimleri ile aynıdır.
    Bölüm anahtarı /kategori Bu makalede açıklanan örnekte bölüm anahtarı olarak /category kullanılır.

    Bu örnek için Benzersiz anahtarlar ekleme veya Analiz depolarını açma. Benzersiz anahtarlar, bölüm anahtarı başına bir veya daha fazla değerin benzersiz olmasını sağlayarak veritabanına bir veri bütünlüğü katmanı eklemenize izin verir. Daha fazla bilgi için bkz. Azure Cosmos DB. Analiz deposu, işlemsel iş yüklerinizi etkilemeden operasyonel verilere karşı büyük ölçekli analizler sağlamak için kullanılır.

    Tamam’ı seçin. Veri Gezgini, yeni veritabanını ve kapsayıcıyı görüntüler.

Örnek verileri ekleme

Artık Veri Gezgini kullanarak yeni kapsayıcınıza veri ekleyebilirsiniz.

  1. Veri Gezgini, Görevler veritabanını genişletin, öğeler kapsayıcısını genişletin. Öğeler' i ve sonra Yeni öğe' yi seçin.

    Azure portalındaki Veri Gezgini'nde yeni belge oluşturma

  2. Şimdi aşağıdaki yapıyla kapsayıcıya bir belge ekleyin.

    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    }
    
  3. JSON 'u Belgeler sekmesine ekledikten sonra Kaydet' i seçin.

    JSON verilerini kopyalayın ve Azure portal Veri Gezgini Kaydet ' i seçin

  4. id özelliği için benzersiz bir değer eklediğiniz yerde bir veya daha fazla belge oluşturun ve kaydedin ve diğer özellikleri uygun şekilde değiştirin. Azure Cosmos DB, verilerinizin bir şemaya uygun olmasını şart koşmadığı için yeni belgelerinizin yapısını istediğiniz şekilde oluşturabilirsiniz.

Verilerinizi sorgulayın

Verilerinizi almak ve filtrelemek Veri Gezgini sorgular kullanabilirsiniz.

  1. Dosyanın Öğeler sekmesinin üst kısmında Veri Gezgini sorgusunu gözden SELECT * FROM c geçirebilirsiniz. Bu sorgu, kapsayıcıdan kimlikle sıra edilen tüm belgeleri alın ve görüntüler.

    Bu dosyada varsayılan Veri Gezgini SELECT * FROM c'dir

  2. Sorguyu değiştirmek için Filtreyi Düzenle'yi seçin, varsayılan sorguyu ile değiştirin ORDER BY c._ts DESC ve ardından Filtre Uygula'ya tıklayın.

    ORDER BY c._ts DESC ekleyerek ve Filtre Uygula’ya tıklayarak varsayılan sorguyu değiştirin

    Değiştirilen sorgu, belgeleri zaman damgalarına göre azalan düzende görüntüler, bu nedenle şimdi ilk olarak ikinci belgeniz listelenir.

    SORGU, DESC'de ORDER BY c._ts filtre uygula'ya tıklamak için değiştirildi

SQL söz dizimi hakkında bilgi sahibiysiniz, sorgu önkatesi kutusuna desteklenen tüm SQL sorgularını girebilirsiniz. Sunucu tarafı iş mantığı Veri Gezgini saklı yordamlar, UFS'ler ve tetikleyiciler oluşturmak için de bu yordamları kullanabilirsiniz.

Veri Gezgini API'lerde Azure portal yerleşik programlı veri erişimi özelliklerine kolay erişim ve erişim sağlar. Ayrıca aktarım hızını ölçeklendirmek, anahtarları ve bağlantı dizelerini almak ve hesap hesabınız için ölçümleri ve SLA'Azure Cosmos DB kullanırsınız.

Örnek uygulamayı kopyalama

Şimdi kod ile çalışmaya geçelim. GitHub'dan bir SQL API'si uygulaması kopyalayalım, bağlantı dizesini ayarlayalım ve uygulamayı çalıştıralım. Verilerle program aracılığıyla çalışmanın ne kadar kolay olduğunu göreceksiniz.

Örnek depoyu kopyalamak için aşağıdaki komutu çalıştırın. Bu komut bilgisayarınızda örnek uygulamanın bir kopyasını oluşturur.

git clone https://github.com/Azure-Samples/azure-spring-data-cosmos-java-sql-api-getting-started.git

Kodu gözden geçirin

Bu adım isteğe bağlıdır. Veritabanı kaynaklarının kodda nasıl oluşturulduğunu öğrenmekle ilgileniyorsanız, aşağıdaki kod parçacıklarını gözden geçirebilirsiniz. Aksi takdirde, Uygulamayı çalıştırma konusuna atlayabilirsiniz.

Uygulama yapılandırma dosyası

Burada Spring Boot ve Spring Data'nın kullanıcı deneyimini nasıl geliştirerek bir Cosmos istemcisi kurma ve Cosmos kaynaklara bağlanma süreci artık kod yerine yapılandırmadır. Uygulama başlangıcında Spring Boot tüm bu ortak işlemi application.properties sayfasındaki ayarları kullanarak halleder:

cosmos.uri=${ACCOUNT_HOST}
cosmos.key=${ACCOUNT_KEY}
cosmos.secondaryKey=${SECONDARY_ACCOUNT_KEY}

dynamic.collection.name=spel-property-collection
# Populate query metrics
cosmos.queryMetricsEnabled=true

Azure Cosmos DB hesabı, veritabanı ve kapsayıcısı oluşturduktan sonra, yapılandırma dosyasındaki boşlukları doldurmanız ve Spring Boot/Spring Data otomatik olarak şunları yapar: (1) URI ve anahtar ile temel alınan bir Java SDK örneği oluşturun ve (2) veritabanına ve kapsayıcıya CosmosClient bağlanın. Artık hazırsın, artık kaynak yönetimi kodu yok!

Java kaynağı

Spring Data value-add, veri deposu üzerinde çalışma için basit, temiz, standartlaştırılmış ve platformdan bağımsız arabiriminden de gelir. Yukarıda bağlantılı Spring Data GitHub örneği üzerinde oluşturma, aşağıda CruD ve Spring Data Azure Cosmos DB ile Azure Cosmos DB belgelerinin işlerini sorgulama örnekleridir.

  • yöntemini kullanarak öğe oluşturma ve save güncelleştirmeler.

    
    logger.info("Saving user : {}", testUser1);
    userRepository.save(testUser1);
    
    
  • Depoda tanımlanan türetilmiş sorgu yöntemini kullanarak nokta okumalar. findByIdAndLastName, için nokta okuma UserRepository gerçekleştirir. Yöntem adı içinde belirtilen alanlar Spring Data'nın ve alanları tarafından tanımlanan bir okuma noktası yürütmesi id için neden lastName olur:

    
    // to find by Id, please specify partition key value if collection is partitioned
    final User result = userRepository.findByIdAndLastName(testUser1.getId(), testUser1.getLastName());
    logger.info("Found user : {}", result);
    
    
  • kullanarak öğe deleteAll siler:

    
    userRepository.deleteAll();
    
    
  • Depo yöntemi adına göre türetilmiş sorgu. Spring Data, java SDK'SQL alanı üzerinde sorgu olarak yöntemini kullanır (bu sorgu okuma UserRepository findByFirstName noktası olarak firstName uygulanamdı):

    
    Flux<User> users = reactiveUserRepository.findByFirstName("testFirstName");
    users.map(u -> {
        logger.info("user is : {}", u);
        return u;
    }).subscribe();
    
    

Uygulamayı çalıştırma

Bu adımda Azure portala dönerek bağlantı dizesi bilgilerinizi alın ve uç nokta bilgileriyle uygulamayı çalıştırın. Bu, uygulamanızın barındırılan veritabanıyla iletişim kurmasına olanak tanır.

  1. git terminal penceresinde cd komutuyla örnek kod klasörüne gidin.

    cd azure-spring-data-cosmos-java-sql-api-getting-started/azure-spring-data-cosmos-java-getting-started/
    
  2. Git terminal penceresinde aşağıdaki komutu kullanarak gerekli Spring Data Azure Cosmos DB paketlerini yükleyin.

    mvn clean package
    
  3. Git terminal penceresinde, Spring Data Azure Cosmos DB uygulamasını başlatmak için aşağıdaki komutu kullanın:

    mvn spring-boot:run
    
  4. Uygulama application.properties'i yükler ve Azure veritabanı Cosmos bağlanır.

  5. Uygulama, yukarıda açıklanan nokta CRUD işlemlerini gerçekleştirecek.

  6. Uygulama türetilmiş bir sorgu gerçekleştirecek.

  7. Uygulama kaynaklarınızı silemez. Ücret ödememek için hesaptan kaynakları temizlemek için portala geri dönebilirsiniz.

Azure portalında SLA'ları gözden geçirme

Bu Azure portal, Cosmos DB aktarım hızı, depolama alanı, kullanılabilirlik, gecikme süresi ve tutarlılığı izler. Bir Azure Cosmos DB Hizmet Düzeyi Sözleşmesi (SLA) ile ilişkili ölçümler, gerçek performansla karşılaştırıldığında SLA değerini gösterir. Bu ölçüm paketi, SLA'larınızı izlemenizi saydam hale gelir.

Ölçümleri ve SLA'ları gözden geçirmek için:

  1. Hesap gezinti Cosmos DB Ölçümler'i seçin.

  2. Gecikme süresi gibi bir sekme seçin ve sağdan bir zaman çerçevesi seçin. Grafiklerde Gerçek ve SLA çizgilerini karşılaştırın.

    Azure Cosmos DB ölçüm paketi

  3. Diğer sekmelerde ölçümleri gözden geçirme.

Kaynakları temizleme

Uygulama ve hesap hesabınızla Azure Cosmos DB, daha fazla ücret ödemeden oluşturduğunuz Azure kaynaklarını silebilirsiniz. Kaynakları silmek için:

  1. Arama Azure portal kaynak grupları için arama ve seçimlerini kullanın.

  2. Listeden bu hızlı başlangıç için oluşturduğunuz kaynak grubunu seçin.

    Silinecek kaynak grubunu seçin

  3. Kaynak grubunun Genel Bakış sayfasında Kaynak grubunu sil'i seçin.

    Kaynak grubunu silme

  4. Sonraki pencerede, silinecek kaynak grubunun adını girin ve Sil'i seçin.

Sonraki adımlar

Bu hızlı başlangıçta Azure Cosmos DB SQL API hesabı oluşturma, Veri Gezgini kullanarak belge veritabanı ve kapsayıcı oluşturma ve aynı şeyi program aracılığıyla yapmak için spring Data uygulamasını çalıştırmayı öğrendiniz. Artık Azure veritabanı veritabanı hesabınıza ek Cosmos aktarabilirsiniz.

Azure Cosmos DB'ye geçiş için kapasite planlaması yapmaya mı çalışıyorsunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkında bilgi kullanabilirsiniz.

  • Mevcut veritabanı kümenizin sanal çekirdek ve sunucu sayısıyla ilgili tüm bilginiz varsa, sanal çekirdek veya vCPUS kullanarak istek birimlerini tahmin hakkında bilgi edinebilirsiniz
  • Geçerli veritabanı iş yükünüz için tipik istek oranlarını biliyorsanız Azure Cosmos DB kapasite planlayıcısı kullanarak istek birimlerini tahmin hakkında bilgi edinin