Azure İşlevleri 2.x ve üzeri için Azure Cosmos DB tetikleyicisi ve bağlamalarına genel bakış

  • Makale

Bu makale kümesinde, Azure İşlevleri 2.x ve üzeri sürümlerde Azure Cosmos DB bağlamalarıyla çalışma açıklanmaktadır. Azure İşlevleri, Azure Cosmos DB için tetikleyici, giriş ve çıkış bağlamalarını destekler.

Eylem Tür
Azure Cosmos DB belgesi oluşturulduğunda veya değiştirildiğinde işlev çalıştırma Tetikleyici
Azure Cosmos DB belgesini okuma Giriş bağlaması
Azure Cosmos DB belgesinde değişiklikleri kaydetme Çıkış bağlaması

Not

Bu başvuru, Azure İşlevleri sürüm 2.x ve üzeri içindir. İşlevler 1.x'te bu bağlamaların nasıl kullanılacağı hakkında bilgi için bkz. Azure İşlevleri 1.x için Azure Cosmos DB bağlamaları.

Bu bağlama ilk olarak DocumentDB olarak adlandırıldı. Azure İşlevleri sürüm 2.x ve üzeri sürümlerde tetikleyici, bağlamalar ve paketin tümü Azure Cosmos DB olarak adlandırılır.

Desteklenen API'ler

Azure Cosmos DB bağlamaları yalnızca NoSQL için Azure Cosmos DB ile kullanılmak üzere desteklenir. Tablo için Azure Cosmos DB desteği, 5.x uzantısından başlayarak Tablo depolama bağlamaları kullanılarak sağlanır. Diğer tüm Azure Cosmos DB API'leri için, MongoDB için Azure Cosmos DB, Cassandra için Azure Cosmos DB ve Apache Gremlin için Azure Cosmos DB gibi API'nizin statik istemcisini kullanarak işlevinizden veritabanına erişmeniz gerekir.

Uzantıyı yükleme

Yüklediğiniz NuGet uzantısı, işlev uygulamanızda kullandığınız C# moduna bağlıdır:

İşlevler yalıtılmış bir C# çalışan işleminde yürütülür. Daha fazla bilgi edinmek için bkz. Yalıtılmış çalışan işleminde C# Azure İşlevleri çalıştırma kılavuzu.

Uzantıyı yükleme işlemi uzantı sürümüne bağlı olarak değişir:

Azure Cosmos DB bağlama uzantısının bu sürümü gizli dizi yerine kimlik kullanarak bağlanma özelliğini tanıtır. İşlev uygulamalarınızı yönetilen kimliklerle yapılandırma öğreticisi için kimlik tabanlı bağlantılarla işlev uygulaması oluşturma öğreticisine bakın.

NuGet paketi sürüm 4.x'i yükleyerek uzantıyı projenize ekleyin.

Uygulamanızı F# kullanarak yazıyorsanız, bu uzantıyı uygulamanın başlangıç yapılandırmasının bir parçası olarak da yapılandırmanız gerekir. veya ConfigureFunctionsWebApplication()çağrısındaConfigureFunctionsWorkerDefaults(), parametre alan bir IFunctionsWorkerApplication temsilci ekleyin. Ardından bu temsilcinin gövdesinde nesnesine çağrı ConfigureCosmosDBExtension() yapın:

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Paket yükleme

Azure Cosmos DB bağlamaları uzantısı, host.json proje dosyanızda belirtilen bir uzantı paketinin parçasıdır. Bağlamanın sürümünü değiştirmek için veya paketler henüz yüklü değilse bu paketi değiştirmeniz gerekebilir. Daha fazla bilgi edinmek için bkz . uzantı paketi.

Azure Cosmos DB SDK'sında şema değişiklikleri nedeniyle, Azure Cosmos DB uzantısının 4.x sürümü Java işlevleri için azure-functions-java-library V3.0.0 gerektirir.

Paketin bu sürümü, gizli dizi yerine kimlik kullanarak bağlanma özelliğini tanıtan Azure Cosmos DB bağlamaları uzantısının 4.x sürümünü içerir. İşlev uygulamalarınızı yönetilen kimliklerle yapılandırma öğreticisi için kimlik tabanlı bağlantılarla işlev uygulaması oluşturma öğreticisine bakın.

Dosyanıza host.json aşağıdaki kodu ekleyerek veya değiştirerek v4 önizleme uzantısı paketinden uzantının bu sürümünü ekleyebilirsiniz:

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.0.0, 5.0.0)"
  }
}

Daha fazla bilgi edinmek için bkz . Uzantılarınızı güncelleştirme.

Bağlama türleri

.NET için desteklenen bağlama türleri, aşağıdakilerden biri olabilecek uzantı sürümüne ve C# yürütme moduna bağlıdır:

Yalıtılmış çalışan işlem sınıfı kitaplığı derlenmiş C# işlevi çalışma zamanından yalıtılmış bir işlemde çalışır.

Modun ve sürümün bağlama türü ayrıntılarını görmek için bir sürüm seçin.

Yalıtılmış çalışan işlemi, aşağıdaki tablolara göre parametre türlerini destekler. Microsoft.Azure.Cosmos'tan türlere bağlama desteği önizleme aşamasındadır.

Cosmos DB tetikleyicisi

İşlevin tek bir belgeyi işlemesini istediğinizde Cosmos DB tetikleyicisi aşağıdaki türlere bağlanabilir:

Type Açıklama
JSON serileştirilebilir türler İşlevler, Cosmos DB değişiklik akışından belgenin JSON verilerinin seri durumdan çıkarılarak düz eski bir CLR nesnesi (POCO) türüne dönüştürülmesi için çalışır.

İşlevin bir grup belgeyi işlemesini istediğinizde, Cosmos DB tetikleyicisi aşağıdaki türlere bağlanabilir:

Type Açıklama
IEnumerable<T>burada T JSON serileştirilebilir bir türdür Toplu işe dahil edilen varlıkların numaralandırması. Her girdi Cosmos DB değişiklik akışından bir belgeyi temsil eder.

Cosmos DB giriş bağlaması

İşlevin tek bir belgeyi işlemesini istediğinizde Cosmos DB giriş bağlaması aşağıdaki türlere bağlanabilir:

Type Açıklama
JSON serileştirilebilir türler İşlevler, belgenin JSON verilerini seri durumdan çıkararak düz eski bir CLR nesnesi (POCO) türüne dönüştürmeye çalışır.

İşlevin bir sorgudan birden çok belgeyi işlemesini istediğinizde, Cosmos DB giriş bağlaması aşağıdaki türlere bağlanabilir:

Type Açıklama
IEnumerable<T>burada T JSON serileştirilebilir bir türdür Sorgu tarafından döndürülen varlıkların numaralandırması. Her girdi bir belgeyi temsil eder.
CosmosClient1 Cosmos DB hesabına bağlı bir istemci.
Veritabanı1 Cosmos DB veritabanına bağlı bir istemci.
Kapsayıcı1 Cosmos DB kapsayıcısına bağlı bir istemci.

1 Bu türleri kullanmak için Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 veya sonraki sürümlerine ve SDK türü bağlamalarına yönelik ortak bağımlılıklara başvurmanız gerekir.

Cosmos DB çıkış bağlaması

İşlevin tek bir belgeye yazmasını istediğinizde Cosmos DB çıkış bağlaması aşağıdaki türlere bağlanabilir:

Type Açıklama
JSON serileştirilebilir türler Belgenin JSON içeriğini temsil eden nesne. İşlevler, düz eski bir CLR nesnesi (POCO) türünü JSON verilerine seri hale getirme girişiminde bulunur.

İşlevin birden çok belgeye yazmasını istediğinizde Cosmos DB çıkış bağlaması aşağıdaki türlere bağlanabilir:

Type Açıklama
T[] burada T JSON serileştirilebilir türüdür Birden çok belge içeren bir dizi. Her girdi bir belgeyi temsil eder.

Diğer çıkış senaryoları için doğrudan Microsoft.Azure.Cosmos'un diğer türleriyle CosmosClient oluşturun ve kullanın. Azure SDK'dan bir istemci türü oluşturmak için bağımlılık ekleme kullanma örneği için bkz . Azure istemcilerini kaydetme.

Özel durumlar ve dönüş kodları

Bağlama Başvuru
Azure Cosmos DB Azure Cosmos DB için HTTP durum kodları

host.json ayarları

Bu bölümde, 2.x ve üzeri sürümlerde bu bağlama için kullanılabilen yapılandırma ayarları açıklanmaktadır. host.json dosyasındaki ayarlar, bir işlev uygulaması örneğindeki tüm işlevler için geçerlidir. Aşağıdaki örnek host.json dosyası, bu bağlama için yalnızca sürüm 2.x+ ayarlarını içerir. 2.x ve sonraki sürümlerdeki işlev uygulaması yapılandırma ayarları hakkında daha fazla bilgi için bkz. Azure İşlevleri için host.json başvuru.

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}
Özellik Varsayılan Açıklama
connectionMode Gateway İşlev tarafından Azure Cosmos DB hizmetine bağlanırken kullanılan bağlantı modu. Seçenekler şunlardır: Direct ve Gateway
userAgentSuffix yok Belirtilen dize değerini tetikleyici veya hizmete bağlama tarafından yapılan tüm isteklere ekler. Bu, belirli bir işlev uygulamasına ve filtrelemeye User Agentgöre Azure İzleyici'deki etkinliği izlemenizi kolaylaştırır.

Sonraki adımlar