Hızlı Başlangıç: Azure Cosmos DB ve API verilerini yönetmek SQL Java uygulaması oluşturma

UYGULANDıĞı YER: SQL API

Bu hızlı başlangıçta, Azure portal'den kopyalanan bir Java uygulamasını kullanarak Cosmos DB SQL API hesabı oluşturur ve GitHub. İlk olarak, Azure portal kullanarak bir Azure Cosmos DB SQL API hesabı oluşturun, ardından SQL Java SDK'sını kullanarak bir Java uygulaması oluşturun ve ardından Java uygulamasını kullanarak Cosmos DB hesabınıza kaynak ekleyin. Azure Cosmos DB, genel dağıtım ve yatay ölçek özellikleriyle belge, tablo, anahtar-değer ve grafik veritabanlarını hızlı bir şekilde oluşturmanıza ve sorgulamanızı sağlayan çok modelli bir veritabanı hizmetidir.

Önemli

Bu hızlı başlangıç yalnızca Azure Cosmos DB Java SDK v4'e tasarlanmıştır. Daha fazla bilgi için lütfen Azure Cosmos DB Java SDK v4Sürüm notları, Mavendeposu, Azure Cosmos DB Java SDK'sı v4performans ipuçları ve Azure Cosmos DB Java SDK'sı v4 sorun giderme kılavuzuna bakın. Şu anda v4'den eski bir sürüm kullanıyorsanız v4'e yükseltme yardımı için Azure Cosmos DB Java SDK'sı v4'e geçiş kılavuzuna 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üzeyinde 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 belgeleriniz içinde her belgeyi bir bölümle eşleyen bölüm anahtarı olacak bir alan seçmeniz gerekir. 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 önemli ölçüde 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-cosmos-java-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.

Zaman uyumlu (eşitleme) API'sini kullanarak veritabanı kaynaklarını yönetme

  • CosmosClient başlatma. CosmosClient, Azure veritabanı hizmeti için istemci tarafı mantıksal Cosmos sağlar. Bu istemci, istekleri hizmete göre yapılandırmak ve çalıştırmak için kullanılır.

    client = new CosmosClientBuilder()
        .endpoint(AccountSettings.HOST)
        .key(AccountSettings.MASTER_KEY)
        //  Setting the preferred location to Cosmos DB Account region
        //  West US is just an example. User should set preferred location to the Cosmos DB region closest to the application
        .preferredRegions(Collections.singletonList("West US"))
        .consistencyLevel(ConsistencyLevel.EVENTUAL)
        .buildClient();
    
    
  • CosmosDatabase Oluşturma.

    CosmosDatabaseResponse cosmosDatabaseResponse = client.createDatabaseIfNotExists(databaseName);
    database = client.getDatabase(cosmosDatabaseResponse.getProperties().getId());
    
  • CosmosContainer Oluşturma.

    CosmosContainerProperties containerProperties =
        new CosmosContainerProperties(containerName, "/lastName");
    
    //  Create container with 400 RU/s
    CosmosContainerResponse cosmosContainerResponse =
        database.createContainerIfNotExists(containerProperties, ThroughputProperties.createManualThroughput(400));
    container = database.getContainer(cosmosContainerResponse.getProperties().getId());
    
  • yöntemini kullanarak öğe createItem oluşturma.

    //  Create item using container that we created using sync client
    
    //  Use lastName as partitionKey for cosmos item
    //  Using appropriate partition key improves the performance of database operations
    CosmosItemRequestOptions cosmosItemRequestOptions = new CosmosItemRequestOptions();
    CosmosItemResponse<Family> item = container.createItem(family, new PartitionKey(family.getLastName()), cosmosItemRequestOptions);
    
  • Nokta okumaları yöntemi kullanılarak readItem gerçekleştirilir.

    try {
        CosmosItemResponse<Family> item = container.readItem(family.getId(), new PartitionKey(family.getLastName()), Family.class);
        double requestCharge = item.getRequestCharge();
        Duration requestLatency = item.getDuration();
        logger.info("Item successfully read with id {} with a charge of {} and within duration {}",
            item.getItem().getId(), requestCharge, requestLatency);
    } catch (CosmosException e) {
        logger.error("Read Item failed with", e);
    }
    
  • SQL JSON üzerinden yapılan sorgular yöntemi kullanılarak queryItems gerçekleştirilir.

    // Set some common query options
    CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions();
    //queryOptions.setEnableCrossPartitionQuery(true); //No longer necessary in SDK v4
    //  Set query metrics enabled to get metrics around query executions
    queryOptions.setQueryMetricsEnabled(true);
    
    CosmosPagedIterable<Family> familiesPagedIterable = container.queryItems(
        "SELECT * FROM Family WHERE Family.lastName IN ('Andersen', 'Wakefield', 'Johnson')", queryOptions, Family.class);
    
    familiesPagedIterable.iterableByPage(10).forEach(cosmosItemPropertiesFeedResponse -> {
        logger.info("Got a page of query result with {} items(s) and request charge of {}",
                cosmosItemPropertiesFeedResponse.getResults().size(), cosmosItemPropertiesFeedResponse.getRequestCharge());
    
        logger.info("Item Ids {}", cosmosItemPropertiesFeedResponse
            .getResults()
            .stream()
            .map(Family::getId)
            .collect(Collectors.toList()));
    });
    

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-cosmos-java-getting-started
    
  2. Git terminal penceresinde aşağıdaki komutu kullanarak gerekli Java paketlerini yükleyin.

    mvn package
    
  3. Git terminal penceresinde, Java uygulamasını başlatmak için aşağıdaki komutu kullanın (SYNCASYNCMODE'yi çalıştırmak için veya çalıştırmak için örnek koda bağlı olarak değiştirin, YOUR_COSMOS_DB_HOSTNAME değerini portaldan tırnak içine alınan URI değeriyle değiştirin ve YOUR_COSMOS_DB_MASTER_KEY yerine portaldan alınan tırnak içine alınan birincil anahtarla sync async değiştirin)

    mvn exec:java@SYNCASYNCMODE -DACCOUNT_HOST=YOUR_COSMOS_DB_HOSTNAME -DACCOUNT_KEY=YOUR_COSMOS_DB_MASTER_KEY
    
    

    Terminal penceresinde, FamilyDB veritabanının oluşturulduğunu belirten bir bildirim görüntülenir.

  4. Uygulama, adıyla veritabanı oluşturur AzureSampleFamilyDB

  5. Uygulama, adıyla kapsayıcı oluşturur FamilyContainer

  6. Uygulama nesne kimliklerini ve bölüm anahtarı değerini (örneğimizde lastName olan) kullanarak nokta okuma işlemleri gerçekleştirecek.

  7. Uygulama, soyadı ('Andersen', 'Wakefield', 'Ileriz') olan tüm aileleri almak için öğeleri sorgular

  8. Uygulama, oluşturulan kaynakları silmez. Kaynakları temizlemek için portala dönün. Ücret oluşmaması için kaynakları hesabınızdan silin.

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 bir Java uygulaması çalıştırmayı öğrendiniz. artık Azure Cosmos DB hesabınıza daha fazla veri aktarabilirsiniz.

Azure Cosmos DB bir geçişe yönelik kapasite planlaması yapılmaya çalışılıyor musunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkında bilgi kullanabilirsiniz.