Azure İşlevleri 2.x ve üzeri için Azure Cosmos DB çıkış bağlaması

Azure Cosmos DB çıkış bağlaması, SQL API'sini kullanarak Azure Cosmos DB veritabanına yeni bir belge yazmanızı sağlar.

Kurulum ve yapılandırma ayrıntıları hakkında bilgi için genel bakışa bakın.

Önemli

Bu makalede, Node.js programlama modelinin birden çok sürümünü desteklemek için sekmeler kullanılır. Genel kullanıma sunulan v4 modeli, JavaScript ve TypeScript geliştiricileri için daha esnek ve sezgisel bir deneyime sahip olacak şekilde tasarlanmıştır. v4 modelinin nasıl çalıştığı hakkında daha fazla bilgi için Azure İşlevleri Node.js geliştirici kılavuzuna bakın. v3 ile v4 arasındaki farklar hakkında daha fazla bilgi edinmek için geçiş kılavuzuna bakın.

Azure İşlevleri, Python için iki programlama modelini destekler. Bağlamalarınızı tanımlama şekliniz seçtiğiniz programlama modeline bağlıdır.

v2

Python v2 programlama modeli, doğrudan Python işlev kodunuzda dekoratörleri kullanarak bağlamaları tanımlamanıza olanak tanır. Daha fazla bilgi için bkz . Python geliştirici kılavuzu.

v1

Python v1 programlama modeli, işlev klasöründeki ayrı bir function.json dosyasında bağlamaları tanımlamanızı gerektirir. Daha fazla bilgi için bkz . Python geliştirici kılavuzu.

Bu makale her iki programlama modelini de destekler.

C# işlevi aşağıdaki C# modlarından biri kullanılarak oluşturulabilir:

• Yalıtılmış çalışan modeli: Çalışma zamanından yalıtılmış bir çalışan işleminde çalışan derlenmiş C# işlevi. LTS ve .NET ve .NET Framework dışındaki sürümlerde çalışan C# işlevlerini desteklemek için yalıtılmış çalışan işlemi gereklidir. Yalıtılmış çalışan işlemi işlevleri için uzantılar ad alanlarını kullanır Microsoft.Azure.Functions.Worker.Extensions.* .
• İşlem içi model: İşlevler çalışma zamanıyla aynı işlemde çalışan derlenmiş C# işlevi. Bu modelin bir varyasyonunda, İşlevler öncelikle C# portalı düzenleme için desteklenen C# betiği kullanılarak çalıştırılabilir. İşlem içi işlevlerin uzantıları ad alanlarını kullanır Microsoft.Azure.WebJobs.Extensions.* .

Önemli

İşlem içi model desteği 10 Kasım 2026'da sona erecektir. Tam destek için uygulamalarınızı yalıtılmış çalışan modeline geçirmenizi kesinlikle öneririz.

Örnek

Aksi belirtilmediği sürece, bu makaledeki örnekler Azure Cosmos DB uzantısının 3.x sürümünü hedeflemektedir. Uzantı sürümü 4.x ile kullanmak için, özellik ve öznitelik adlarındaki dizeyi collection ve connection_string_setting ile containerconnectiondeğiştirmeniz gerekir.

Yalıtılmış çalışan modeli

Aşağıdaki kod bir MyDocument tür tanımlar:

public class MyDocument
{
    public string Id { get; set; }

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

Aşağıdaki örnekte, dönüş türü tetikleyici bağlama parametresinden belgelerin değiştirilmiş bir listesi olan bir IReadOnlyList<T>değeridir:

using System.Collections.Generic;
using System.Linq;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace SampleApp
{
    public class CosmosDBFunction
    {
        private readonly ILogger<CosmosDBFunction> _logger;

        public CosmosDBFunction(ILogger<CosmosDBFunction> logger)
        {
            _logger = logger;
        }

        //<docsnippet_exponential_backoff_retry_example>
        [Function(nameof(CosmosDBFunction))]
        [ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
        [CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
        public object Run(
            [CosmosDBTrigger(
                "%CosmosDb%",
                "%CosmosContainerIn%",
                Connection = "CosmosDBConnection",
                LeaseContainerName = "leases",
                CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
            FunctionContext context)
        {
            if (input != null && input.Any())
            {
                foreach (var doc in input)
                {
                    _logger.LogInformation("Doc Id: {id}", doc.Id);
                }

                // Cosmos Output
                return input.Select(p => new { id = p.Id });
            }

            return null;
        }
        //</docsnippet_exponential_backoff_retry_example>
    }

İşlem içi model

Bu bölüm aşağıdaki örnekleri içerir:

• Kuyruk tetikleyicisi, bir belge yazma
• Kuyruk tetikleyicisi, bir belge yazma (v4 uzantısı)
• Kuyruk tetikleyicisi, IAsyncCollector kullanarak belge yazma

Örnekler basit ToDoItem bir türe başvurur:

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

Kuyruk tetikleyicisi, bir belge yazma

Aşağıdaki örnekte, Kuyruk depolamadan iletide sağlanan verileri kullanarak veritabanına belge ekleyen bir C# işlevi gösterilmektedir.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Kuyruk tetikleyicisi, bir belge yazma (v4 uzantısı)

Azure Cosmos DB uzantısı sürüm 4.x veya üzerini kullanan uygulamalar aşağıda gösterilen farklı öznitelik özelliklerine sahip olacaktır. Aşağıdaki örnekte, Kuyruk depolamadan iletide sağlanan verileri kullanarak veritabanına belge ekleyen bir C# işlevi gösterilmektedir.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Kuyruk tetikleyicisi, IAsyncCollector kullanarak belge yazma

Aşağıdaki örnekte, bir kuyruk iletisi JSON'unda sağlanan verileri kullanarak veritabanına belge koleksiyonu ekleyen bir C# işlevi gösterilmektedir.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

• Kuyruk tetikleyicisi, dönüş değeri aracılığıyla iletiyi veritabanına kaydedin
• HTTP tetikleyicisi, dönüş değeri aracılığıyla bir belgeyi veritabanına kaydedin
• HTTP tetikleyicisi, OutputBinding aracılığıyla bir belgeyi veritabanına kaydedin
• HTTP tetikleyicisi, OutputBinding aracılığıyla veritabanına birden çok belge kaydedin

Kuyruk tetikleyicisi, dönüş değeri aracılığıyla iletiyi veritabanına kaydedin

Aşağıdaki örnekte, Kuyruk depolamadaki bir iletiden alınan verilerle veritabanına belge ekleyen bir Java işlevi gösterilmektedir.

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

HTTP tetikleyicisi, dönüş değeri aracılığıyla bir belgeyi veritabanına kaydedin

Aşağıdaki örnekte, imzası ile @CosmosDBOutput ek açıklama eklenmiş ve türünde Stringdönüş değeri olan bir Java işlevi gösterilmektedir. İşlev tarafından döndürülen JSON belgesi otomatik olarak ilgili Azure Cosmos DB koleksiyonuna yazılır.

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

HTTP tetikleyicisi, OutputBinding aracılığıyla bir belgeyi veritabanına kaydedin

Aşağıdaki örnekte, çıkış parametresi aracılığıyla Azure Cosmos DB'ye belge yazan bir OutputBinding<T> Java işlevi gösterilmektedir. Bu örnekte, parametresine outputItem işlev imzası değil ile @CosmosDBOutputek açıklama eklenmelidir. işlevinin OutputBinding<T> kullanılması, işlevinizin belgeyi Azure Cosmos DB'ye yazmak için bağlamadan yararlanmasını sağlarken, işlev çağırana JSON veya XML belgesi gibi farklı bir değer döndürmeye de olanak tanır.

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

HTTP tetikleyicisi, OutputBinding aracılığıyla veritabanına birden çok belge kaydedin

Aşağıdaki örnekte, bir çıkış parametresi aracılığıyla Azure Cosmos DB'ye birden çok belge yazan bir OutputBinding<T> Java işlevi gösterilmektedir. Bu örnekte, parametreye outputItem işlev imzası değil ile @CosmosDBOutputek açıklama eklenir. Çıkış parametresi, outputItem şablon parametre türü olarak nesnelerin bir listesine ToDoItem sahiptir. işlevinin OutputBinding<T> kullanılması, bağlamadan yararlanarak belgeleri Azure Cosmos DB'ye yazmanızı sağlarken, işlev çağırana JSON veya XML belgesi gibi farklı bir değer döndürmeye de olanak tanır.

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

Java işlevleri çalışma zamanı kitaplığında, Azure Cosmos DB'ye yazılacak parametrelerde ek açıklamayı kullanın@CosmosDBOutput. Ek açıklama parametre türü olmalıdır OutputBinding<T>; burada T yerel bir Java türü veya POJO olmalıdır.

Model v4

Aşağıdaki örnekte, aşağıdaki biçimde JSON alan bir kuyruk için depolama kuyruğu tarafından tetiklenen TypeScript işlevi gösterilmektedir:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

İşlev, her kayıt için aşağıdaki biçimde Azure Cosmos DB belgeleri oluşturur:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

TypeScript kodu şu şekildedir:

import { app, InvocationContext, output } from '@azure/functions';

interface MyQueueItem {
    name: string;
    employeeId: string;
    address: string;
}

interface MyCosmosItem {
    id: string;
    name: string;
    employeeId: string;
    address: string;
}

export async function storageQueueTrigger1(queueItem: MyQueueItem, context: InvocationContext): Promise<MyCosmosItem> {
    return {
        id: `${queueItem.name}-${queueItem.employeeId}`,
        name: queueItem.name,
        employeeId: queueItem.employeeId,
        address: queueItem.address,
    };
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: output.cosmosDB({
        databaseName: 'MyDatabase',
        collectionName: 'MyCollection',
        createIfNotExists: true,
        connectionStringSetting: 'MyAccount_COSMOSDB',
    }),
    handler: storageQueueTrigger1,
});

Birden çok belgenin çıktısını almak için tek bir nesne yerine dizi döndürebilirsiniz. Örneğin:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

Model v3

Model v3 için TypeScript örnekleri belgelenmez.

Model v4

Aşağıdaki örnekte, aşağıdaki biçimde JSON alan bir kuyruk için depolama kuyruğu tarafından tetiklenen JavaScript işlevi gösterilmektedir:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

İşlev, her kayıt için aşağıdaki biçimde Azure Cosmos DB belgeleri oluşturur:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

JavaScript kodu şu şekildedir:

const { app, output } = require('@azure/functions');

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: true,
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'inputqueue',
    connection: 'MyStorageConnectionAppSetting',
    return: cosmosOutput,
    handler: (queueItem, context) => {
        return {
            id: `${queueItem.name}-${queueItem.employeeId}`,
            name: queueItem.name,
            employeeId: queueItem.employeeId,
            address: queueItem.address,
        };
    },
});

Birden çok belgenin çıktısını almak için tek bir nesne yerine dizi döndürebilirsiniz. Örneğin:

return [
    {
        id: 'John Henry-123456',
        name: 'John Henry',
        employeeId: '123456',
        address: 'A town nearby',
    },
    {
        id: 'John Doe-123457',
        name: 'John Doe',
        employeeId: '123457',
        address: 'A town far away',
    },
];

Model v3

Aşağıdaki örnekte, bir function.json dosyasındaki Azure Cosmos DB çıkış bağlaması ve bağlamayı kullanan bir JavaScript işlevi gösterilmektedir. İşlev, aşağıdaki biçimde JSON alan bir kuyruk için kuyruk giriş bağlaması kullanır:

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

İşlev, her kayıt için aşağıdaki biçimde Azure Cosmos DB belgeleri oluşturur:

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

function.json dosyasındaki bağlama verileri aşağıdadır:

{
    "name": "employeeDocument",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

Yapılandırma bölümünde bu özellikler açıklanır.

JavaScript kodu şu şekildedir:

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

Toplu ekleme için önce nesneleri ekleyin ve sonra stringify işlevini çalıştırın. JavaScript kodu şu şekildedir:

    module.exports = async function (context) {

        context.bindings.employeeDocument = JSON.stringify([
        {
            "id": "John Henry-123456",
            "name": "John Henry",
            "employeeId": "123456",
            "address": "A town nearby"
        },
        {
            "id": "John Doe-123457",
            "name": "John Doe",
            "employeeId": "123457",
            "address": "A town far away"
        }]);
    };

Aşağıdaki örnekte, çıkış bağlaması kullanarak Azure Cosmos DB'ye veri yazma işlemi gösterilmektedir. Bağlama işlevin yapılandırma dosyasında (functions.json) bildirilir ve bir kuyruk iletisinden veri alır ve bir Azure Cosmos DB belgesine yazar.

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
} 

run.ps1 dosyasında, işlevinden döndürülen nesne veritabanında kalıcı olan bir EmployeeDocument nesneyle eşlenir.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
} 

Aşağıdaki örnekte, bir işlevin çıktısı olarak Bir Azure Cosmos DB veritabanına belge yazma işlemi gösterilmektedir. Örnek, v1 veya v2 Python programlama modelini kullanıp kullanmadığınıza bağlıdır.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

v1

Bağlama tanımı, türü olarak ayarlandığı cosmosDBfunction.json tanımlanır.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

Veritabanına yazmak için, veritabanı parametresinin set yöntemine bir belge nesnesi geçirin.

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

Özellikler

hem işlem içi hem de yalıtılmış çalışan işlemi C# kitaplıkları işlevi tanımlamak için öznitelikleri kullanır. Bunun yerine C# betiği, C# betik kılavuzunda açıklandığı gibi bir function.json yapılandırma dosyası kullanır.

Uzantı 4.x+

Öznitelik özelliği	Açıklama
Bağlantı	İzlenen Azure Cosmos DB hesabına nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Daha fazla bilgi için bkz. Bağlan ions.
Databasename	Kapsayıcının izlendiği Azure Cosmos DB veritabanının adı.
ContainerName	İzlenen kapsayıcının adı.
CreateIfNotExists	Kapsayıcının mevcut olmadığında oluşturulup oluşturulmadığını gösteren boole değeri. Varsayılan değer false'tur çünkü yeni kapsayıcılar ayrılmış aktarım hızıyla oluşturulur ve bunun maliyet etkileri vardır. Daha fazla bilgi için bkz. fiyatlandırma sayfası.
PartitionKey	True CreateIfNotExists olduğunda, oluşturulan kapsayıcı için bölüm anahtarı yolunu tanımlar. Bağlama parametreleri içerebilir.
ContainerThroughput	True CreateIfNotExists olduğunda, oluşturulan kapsayıcının aktarım hızını tanımlar.
PreferredLocations	(İsteğe bağlı) Azure Cosmos DB hizmetinde coğrafi olarak çoğaltılan veritabanı hesapları için tercih edilen konumları (bölgeleri) tanımlar. Değerler virgülle ayrılmış olmalıdır. Örneğin, East US,South Central US,North Europe.

İşlevler 2.x+

Öznitelik özelliği	Açıklama
Bağlan ionStringSetting	İzlenen Azure Cosmos DB hesabına nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Daha fazla bilgi için bkz. Bağlan ions.
Databasename	Koleksiyonun izlendiği Azure Cosmos DB veritabanının adı.
Toplamaadı	İzlenen koleksiyonun adı.
CreateIfNotExists	Koleksiyonun mevcut olmadığında oluşturulup oluşturulmadığını gösteren boole değeri. Varsayılan değer false'tur çünkü yeni koleksiyonlar ayrılmış aktarım hızıyla oluşturulur ve bu da maliyeti etkiler. Daha fazla bilgi için bkz. fiyatlandırma sayfası.
PartitionKey	True CreateIfNotExists olduğunda, oluşturulan koleksiyon için bölüm anahtarı yolunu tanımlar. Bağlama parametreleri içerebilir.
CollectionThroughput	True CreateIfNotExists olduğunda, oluşturulan koleksiyonun aktarım hızını tanımlar.
PreferredLocations	(İsteğe bağlı) Azure Cosmos DB hizmetinde coğrafi olarak çoğaltılan veritabanı hesapları için tercih edilen konumları (bölgeleri) tanımlar. Değerler virgülle ayrılmış olmalıdır. Örneğin, East US,South Central US,North Europe.
UseMultipleWriteLocations	(İsteğe bağlı) ile PreferredLocationsbirlikte olarak ayarlandığındatrue, Azure Cosmos DB hizmetinde çok bölgeli yazma işlemleri desteklenir.

Uzantı 4.x+

Öznitelik özelliği	Açıklama
Bağlantı	İzlenen Azure Cosmos DB hesabına nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Daha fazla bilgi için bkz. Bağlan ions.
Databasename	Kapsayıcının izlendiği Azure Cosmos DB veritabanının adı.
ContainerName	İzlenen kapsayıcının adı.
CreateIfNotExists	Kapsayıcının mevcut olmadığında oluşturulup oluşturulmadığını gösteren boole değeri. Varsayılan değer false'tur çünkü yeni kapsayıcılar ayrılmış aktarım hızıyla oluşturulur ve bunun maliyet etkileri vardır. Daha fazla bilgi için bkz. fiyatlandırma sayfası.
PartitionKey	True CreateIfNotExists olduğunda, oluşturulan kapsayıcı için bölüm anahtarı yolunu tanımlar. Bağlama parametreleri içerebilir.
ContainerThroughput	True CreateIfNotExists olduğunda, oluşturulan kapsayıcının aktarım hızını tanımlar.
PreferredLocations	(İsteğe bağlı) Azure Cosmos DB hizmetinde coğrafi olarak çoğaltılan veritabanı hesapları için tercih edilen konumları (bölgeleri) tanımlar. Değerler virgülle ayrılmış olmalıdır. Örneğin, East US,South Central US,North Europe.

İşlevler 2.x+

Öznitelik özelliği	Açıklama
Bağlan ionStringSetting	İzlenen Azure Cosmos DB hesabına nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Daha fazla bilgi için bkz. Bağlan ions.
Databasename	Koleksiyonun izlendiği Azure Cosmos DB veritabanının adı.
Toplamaadı	İzlenen koleksiyonun adı.
CreateIfNotExists	Koleksiyonun mevcut olmadığında oluşturulup oluşturulmadığını gösteren boole değeri. Varsayılan değer false'tur çünkü yeni koleksiyonlar ayrılmış aktarım hızıyla oluşturulur ve bu da maliyeti etkiler. Daha fazla bilgi için bkz. fiyatlandırma sayfası.
PartitionKey	True CreateIfNotExists olduğunda, oluşturulan koleksiyon için bölüm anahtarı yolunu tanımlar. Bağlama parametreleri içerebilir.
CollectionThroughput	True CreateIfNotExists olduğunda, oluşturulan koleksiyonun aktarım hızını tanımlar.
PreferredLocations	(İsteğe bağlı) Azure Cosmos DB hizmetinde coğrafi olarak çoğaltılan veritabanı hesapları için tercih edilen konumları (bölgeleri) tanımlar. Değerler virgülle ayrılmış olmalıdır. Örneğin, East US,South Central US,North Europe.
UseMultipleWriteLocations	(İsteğe bağlı) ile PreferredLocationsbirlikte olarak ayarlandığındatrue, Azure Cosmos DB hizmetinde çok bölgeli yazma işlemleri desteklenir.

Dekoratörler

Yalnızca Python v2 programlama modeli için geçerlidir.

Bir dekoratör kullanılarak tanımlanan Python v2 işlevleri için, üzerinde aşağıdaki özellikler:cosmos_db_output

Özellik	Açıklama
arg_name	Değişiklikleri olan belgelerin listesini temsil eden işlev kodunda kullanılan değişken adı.
database_name	Koleksiyonun izlendiği Azure Cosmos DB veritabanının adı.
collection_name	İzlenen Azure Cosmos DB koleksiyonunun adı.
create_if_not_exists	Veritabanı ve koleksiyon yoksa oluşturulup oluşturulmayacağını gösteren Boole değeri.
connection_string_setting	İzlenen Azure Cosmos DB'nin bağlantı dizesi.

function.json kullanılarak tanımlanan Python işlevleri için Yapılandırma bölümüne bakın.

Ek Açıklamalar

Java işlevleri çalışma zamanı kitaplığında@CosmosDBOutput, Azure Cosmos DB'ye yazan parametrelerde ek açıklamayı kullanın. Ek açıklama aşağıdaki özellikleri destekler:

• Adı
• connectionStringSetting
• Databasename
• Toplamaadı
• createIfNotExists
• Datatype
• partitionKey
• preferredLocations
• useMultipleWriteLocations

Yapılandırma

Yalnızca Python v1 programlama modeli için geçerlidir.

Model v4

Aşağıdaki tabloda, yöntemine geçirilen output.cosmosDB() nesnede options ayarlayabileceğiniz özellikler açıklanmaktadır. type, directionve name özellikleri v4 modeline uygulanmaz.

Model v3

Aşağıdaki tabloda, function.json dosyasında ayarladığınız bağlama yapılandırma özellikleri açıklanır ve burada özellikler uzantı sürümüne göre farklılık gösterir:

Aşağıdaki tabloda, function.json dosyasında ayarladığınız bağlama yapılandırma özellikleri açıklanır ve burada özellikler uzantı sürümüne göre farklılık gösterir:

Uzantı 4.x+

function.json özelliği	Açıklama
Bağlantı	İzlenen Azure Cosmos DB hesabına nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Daha fazla bilgi için bkz. Bağlan ions.
Databasename	Kapsayıcının izlendiği Azure Cosmos DB veritabanının adı.
containerName	İzlenen kapsayıcının adı.
createIfNotExists	Kapsayıcının mevcut olmadığında oluşturulup oluşturulmadığını gösteren boole değeri. Varsayılan değer false'tur çünkü yeni kapsayıcılar ayrılmış aktarım hızıyla oluşturulur ve bunun maliyet etkileri vardır. Daha fazla bilgi için bkz. fiyatlandırma sayfası.
partitionKey	True createIfNotExists olduğunda, oluşturulan kapsayıcı için bölüm anahtarı yolunu tanımlar. Bağlama parametreleri içerebilir.
containerThroughput	True createIfNotExists olduğunda, oluşturulan kapsayıcının aktarım hızını tanımlar.
preferredLocations	(İsteğe bağlı) Azure Cosmos DB hizmetinde coğrafi olarak çoğaltılan veritabanı hesapları için tercih edilen konumları (bölgeleri) tanımlar. Değerler virgülle ayrılmış olmalıdır. Örneğin, East US,South Central US,North Europe.

İşlevler 2.x+

function.json özelliği	Açıklama
connectionStringSetting	İzlenen Azure Cosmos DB hesabına nasıl bağlanıldığını belirten bir uygulama ayarının veya ayar koleksiyonunun adı. Daha fazla bilgi için bkz. Bağlan ions.
Databasename	Koleksiyonun izlendiği Azure Cosmos DB veritabanının adı.
Toplamaadı	İzlenen koleksiyonun adı.
createIfNotExists	Koleksiyonun mevcut olmadığında oluşturulup oluşturulmadığını gösteren boole değeri. Varsayılan değer false'tur çünkü yeni koleksiyonlar ayrılmış aktarım hızıyla oluşturulur ve bu da maliyeti etkiler. Daha fazla bilgi için bkz. fiyatlandırma sayfası.
partitionKey	True createIfNotExists olduğunda, oluşturulan koleksiyon için bölüm anahtarı yolunu tanımlar. Bağlama parametreleri içerebilir.
collectionThroughput	True createIfNotExists olduğunda, oluşturulan koleksiyonun aktarım hızını tanımlar.
preferredLocations	(İsteğe bağlı) Azure Cosmos DB hizmetinde coğrafi olarak çoğaltılan veritabanı hesapları için tercih edilen konumları (bölgeleri) tanımlar. Değerler virgülle ayrılmış olmalıdır. Örneğin, East US,South Central US,North Europe.
useMultipleWriteLocations	(İsteğe bağlı) ile preferredLocationsbirlikte olarak ayarlandığındatrue, Azure Cosmos DB hizmetinde çok bölgeli yazma işlemleri desteklenir.

Tam örnekler için Örnek bölümüne bakın.

Kullanım

Varsayılan olarak, işlevinizdeki çıkış parametresine yazdığınızda veritabanınızda bir belge oluşturulur. Çıkış parametresine geçirilen JSON nesnesinde özelliğini belirterek id çıktı belgesinin belge kimliğini belirtmelisiniz.

Not

Var olan bir belgenin kimliğini belirttiğinizde, yeni çıktı belgesi bu belgenin üzerine yazılır.

Cosmos DB çıkış bağlaması tarafından desteklenen parametre türü İşlevler çalışma zamanı sürümüne, uzantı paketi sürümüne ve kullanılan C# modalitesine bağlıdır.

Uzantı 4.x+

Desteklenen türlerin listesi için bkz. Bağlama türleri.

İşlevler 2.x+

Desteklenen türlerin listesi için bkz. Bağlama türleri.

Uzantı 4.x+

İş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'tan türler oluşturun ve kullanın.

İşlevler 2.x+

Desteklenen türlerin listesi için bkz. Bağlama türleri.

Bağlantılar

connectionStringSetting/connection ve leaseConnectionStringSetting/leaseConnection özellikleri, uygulamanın Azure Cosmos DB'ye nasıl bağlanması gerektiğini belirten ortam yapılandırmasına başvurulardır. Bunlar şunları belirtebilir:

• bağlantı dizesi içeren bir uygulama ayarının adı
• Birden çok uygulama ayarı için paylaşılan ön ekin adı ve birlikte kimlik tabanlı bağlantı tanımlama. Bu seçenek yalnızca uzantının connectionleaseConnection4.x veya sonraki sürümlerinde kullanılabilir.

Yapılandırılan değer hem tek bir ayar için tam eşleşme hem de diğer ayarlar için bir ön ek eşleşmesiyse, tam eşleşme kullanılır.

Connection string

Veritabanı hesabınızın bağlantı dizesi, bağlama yapılandırmasının bağlantı özelliği tarafından belirtilen değerle eşleşen bir adla bir uygulama ayarında depolanmalıdır.

Kimlik tabanlı bağlantılar

Uzantının 4.x veya üzeri bir sürümünü kullanıyorsanız, gizli dizi içeren bir bağlantı dizesi kullanmak yerine uygulamanın bir Microsoft Entra kimliği kullanmasını sağlayabilirsiniz. Bunu yapmak için, tetikleyici ve bağlama yapılandırmasındaki bağlantı özelliğine eşlenen ortak bir ön ek altında ayarları tanımlayabilirsiniz.

Bu modda uzantı aşağıdaki özellikleri gerektirir:

Özellik	Ortam değişkeni şablonu	Açıklama	Örnek değer
Hesap Uç Noktası	<CONNECTION_NAME_PREFIX>__accountEndpoint	Azure Cosmos DB hesap uç noktası URI'si.	<https:// database_account_name.documents.azure.com:443/>

Bağlantıyı özelleştirmek için ek özellikler ayarlanabilir. Bkz. Kimlik tabanlı bağlantılar için ortak özellikler.

Azure İşlevleri hizmetinde barındırıldığında, kimlik tabanlı bağlantılar yönetilen kimlik kullanır. Ve özellikleriyle credentialclientID kullanıcı tarafından atanan bir kimlik belirtilse de, sistem tarafından atanan kimlik varsayılan olarak kullanılır. Kullanıcı tarafından atanan kimliği kaynak kimliğiyle yapılandırmanın desteklenmediğini unutmayın. Yerel geliştirme gibi diğer bağlamlarda çalıştırıldığında, bunun yerine geliştirici kimliğiniz kullanılır, ancak bu özelleştirilebilir. Bkz. Kimlik tabanlı bağlantılarla yerel geliştirme.

Kimliğe izin verme

Hangi kimlik kullanılıyorsa, hedeflenen eylemleri gerçekleştirmek için izinlere sahip olmalıdır. Çoğu Azure hizmeti için bu, bu izinleri sağlayan yerleşik veya özel rolleri kullanarak Azure RBAC'de bir rol atamanız gerektiği anlamına gelir.

Önemli

Bazı izinler, tüm bağlamlar için gerekli olmayan hedef hizmet tarafından gösterilebilir. Mümkün olduğunda, kimliğe yalnızca gerekli ayrıcalıkları sağlayarak en az ayrıcalık ilkesine uyun. Örneğin, uygulamanın yalnızca bir veri kaynağından okuyabilmesi gerekiyorsa, yalnızca okuma izni olan bir rol kullanın. Okuma işlemi için aşırı izin olduğundan, bu hizmete yazmaya da izin veren bir rol atamak uygun olmaz. Benzer şekilde, rol atamasının kapsamının yalnızca okunması gereken kaynaklara göre ayarlandığından emin olmak istersiniz.

Cosmos DB, veri işlemleri için Azure RBAC kullanmaz. Bunun yerine, benzer kavramlar üzerine oluşturulmuş bir Cosmos DB yerleşik RBAC sistemi kullanır. Çalışma zamanında veritabanı hesabınıza erişim sağlayan bir rol ataması oluşturmanız gerekir. Sahip gibi Azure RBAC Yönetimi rolleri yeterli değildir. Aşağıdaki tabloda, Azure Cosmos DB uzantısı normal işlemde kullanılırken önerilen yerleşik roller gösterilmektedir. Uygulamanız, yazdığınız koda göre ek izinler gerektirebilir.

Bağlama türü	Örnek yerleşik roller1
Tetikleyici2	Cosmos DB Yerleşik Veri Katkıda Bulunanı
Giriş bağlaması	Cosmos DB Yerleşik Veri Okuyucusu
Çıkış bağlaması	Cosmos DB Yerleşik Veri Katkıda Bulunanı

¹ Bu roller Azure RBAC rol atamasında kullanılamaz. Bu rolleri atama hakkında ayrıntılı bilgi için Cosmos DB yerleşik RBAC sistemi belgelerine bakın.

² Cosmos DB, kimlik kullanırken kapsayıcı oluşturmayı bir yönetim işlemi olarak ele alır. Tetikleyici için veri düzlemi işlemi olarak kullanılamaz. İşlevinizi ayarlamadan önce tetikleyicinin ihtiyaç duyduğu kapsayıcıları (kira kapsayıcısı dahil) oluşturduğunuzdan emin olmanız gerekir.

Özel durumlar ve dönüş kodları

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

Sonraki adımlar

• 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ğlama)