共用方式為

適用於 Azure Functions 2.x 和更新版本的 Azure Cosmos DB 輸入系結

  • 發行項

Azure Cosmos DB 輸入繫結會使用 SQL API 來擷取一或多個 Azure Cosmos DB 文件，並傳遞給函式的輸入參數。 您可以叫用函式的觸發程序作為基礎來判斷文件識別碼或查詢參數。

如需安裝和組態詳細數據的詳細資訊，請參閱概 觀。

注意

分割集合時，查閱作業也必須指定分割區索引鍵值。

重要

本文使用索引標籤來支援多個版本的 Node.js 程式設計模型。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活且更直覺的體驗。 如需 v4 模型運作方式的更多詳細資料，請參閱 Azure Functions Node.js 開發人員指南。 若要深入了解 v3 與 v4 之間的差異，請參閱移轉指南。

Azure Functions 支援兩種適用於 Python 的程式設計模型。 您定義系結的方式取決於您所選擇的程式設計模型。

Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。 如需詳細資訊，請參閱 Python 開發人員指南。

本文支援這兩種程序設計模型。

範例

除非另有說明，否則本文中的範例會以 Azure Cosmos DB 擴充功能 3.x 版為目標。 若要搭配 4.x 版的延伸模組使用，您必須將 屬性和屬性名稱中的字串 collection 取代為 container。

您可以使用下列其中一種 C# 模式來建立 C# 函式：

  • 隔離的背景工作模型：在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 需要隔離的背景工作進程，才能支援在 LTS 和非 LTS 版本 .NET 和 .NET Framework 上執行的 C# 函式。 隔離背景工作進程函式的延伸模組會使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空間。
  • 同進程模型：在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。 在此模型的變化中，函式可以使用 C# 腳本來執行，主要支援 C# 入口網站編輯。 進程內函式的延伸模組會使用 Microsoft.Azure.WebJobs.Extensions.* 命名空間。

重要

內含式模型支援將於 2026 年 11 月 10 日結束。 強烈建議您將應用程式移轉至隔離式背景工作角色模型，以取得完整支援。

本節包含需要 3.x 版 Azure Cosmos DB 擴充功能和 5.x 版 Azure 儲存體 擴充功能的範例。 如果函式應用程式中尚未存在，請新增下列 NuGet 套件的參考：

這些範例會參考簡單的 ToDoItem 類型：

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

佇列觸發程式，從 JSON 查閱標識符

下列範例顯示擷取單一檔的函式。 函式是由記憶體佇列中的 JSON 訊息所觸發。 佇列觸發程式會將 JSON 剖析為 類型的 ToDoItemLookup物件，其中包含要擷取的標識碼和數據分割索引鍵值。 該標識碼和數據分割索引鍵值可用來從指定的資料庫和集合傳回 ToDoItem 檔。

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

本區段包含下列範例：

這些範例會參考簡單的 ToDoItem 類型：

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

HTTP 觸發程式，從查詢字串查閱標識碼 - 字串參數

下列範例顯示擷取單一檔的Java函式。 函式會由 HTTP 要求觸發，該 HTTP 要求會使用查詢字串指定要查閱的識別碼和分割區索引鍵值。 該標識碼和數據分割索引鍵值是用來從指定的資料庫和集合，以 String 格式擷取檔。

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

在 Java 函式運行時間連結庫中，對 @CosmosDBInput 值來自 Azure Cosmos DB 的函式參數使用註釋。 此批注可以搭配原生 Java 類型、POJO 或使用 可為 Null 的值使用 Optional<T>。

HTTP 觸發程式，從查詢字串查詢識別碼 - POJO 參數

下列範例顯示擷取單一檔的Java函式。 函式會由 HTTP 要求觸發，該 HTTP 要求會使用查詢字串指定要查閱的識別碼和分割區索引鍵值。 用來從指定的資料庫和集合擷取檔的標識碼和數據分割索引鍵值。 接著，文件會轉換成先前建立的 ToDoItem POJO實例，並當做自變數傳遞至函式。

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP 觸發程序，從路由資料中查閱識別碼

下列範例顯示擷取單一檔的Java函式。 此函式是由 HTTP 要求所觸發，該要求會使用路由參數來指定要查閱的標識碼和數據分割索引鍵值。 該識別元和分割區索引鍵值可用來從指定的資料庫和集合擷取檔，並將它傳回為 Optional<String>。

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

HTTP 觸發程式，使用 SqlQuery 從路由數據查閱標識碼

下列範例顯示擷取單一檔的Java函式。 此函式是由 HTTP 要求觸發，該要求會使用路由參數來指定要查閱的標識碼。 該標識碼可用來從指定的資料庫和集合擷取檔，並將結果集 ToDoItem[]轉換成 ，因為可能會根據查詢準則傳回許多檔。

注意

如果您需要只依標識碼進行查詢，建議您使用查閱，例如先前的 範例，因為它會耗用較少的 要求單位。 點讀取作業 （GET） 比依標識碼的查詢更有效率 。

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP 觸發程式，使用 SqlQuery 從路由數據取得多個檔

下列範例顯示擷取多個檔的 Java 函式。 此函式是由 HTTP 要求觸發，該要求會使用路由參數 desc 來指定要在欄位中搜尋的 description 字串。 搜尋字詞可用來從指定的資料庫和集合擷取檔的集合，將結果集 ToDoItem[] 轉換成，並將它當做自變數傳遞至 函式。

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

本節包含下列範例，這些範例會藉由指定來自各種來源的標識符值來讀取單一檔：

佇列觸發程式，從 JSON 查閱標識符

下列範例顯示可 讀取單一檔的 TypeScript 函式 ，並更新文件的文字值。

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

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

interface MyDocument {
    text: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const doc = <MyDocument>context.extraInputs.get(cosmosInput);
    doc.text = 'This was updated!';
    context.extraOutputs.set(cosmosOutput, doc);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: storageQueueTrigger1,
});

HTTP 觸發程序，從查詢字串中查閱識別碼

下列範例顯示會 擷取單一檔的 TypeScript 函式 。 函式會由 HTTP 要求觸發，該 HTTP 要求會使用查詢字串指定要查閱的識別碼和分割區索引鍵值。 該識別碼和分割區索引鍵值會用來從指定的資料庫和集合中擷取 ToDoItem 文件。

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

HTTP 觸發程序，從路由資料中查閱識別碼

下列範例顯示會 擷取單一檔的 TypeScript 函式 。 函式會由 HTTP 要求觸發，該 HTTP 要求會使用路由資料指定要查閱的識別碼和分割區索引鍵值。 該識別碼和分割區索引鍵值會用來從指定的資料庫和集合中擷取 ToDoItem 文件。

import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

佇列觸發程序，使用 SqlQuery 取得多個文件

下列範例示範使用 佇列觸發程式自定義查詢參數，擷取 SQL 查詢所指定的多個檔的 TypeScript 函 式。

佇列觸發程序會提供參數 departmentId。 { "departmentId" : "Finance" } 的佇列訊息會傳回財務部門的所有記錄。

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface MyDocument {}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
    for (const document of documents) {
        // operate on each document
    }
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: storageQueueTrigger1,
});

本節包含下列範例，這些範例會藉由指定來自各種來源的標識符值來讀取單一檔：

佇列觸發程式，從 JSON 查閱標識符

下列範例顯示 JavaScript 函式 ，可讀取單一檔並更新檔的文字值。

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

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

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: (queueItem, context) => {
        const doc = context.extraInputs.get(cosmosInput);
        doc.text = 'This was updated!';
        context.extraOutputs.set(cosmosOutput, doc);
    },
});

HTTP 觸發程序，從查詢字串中查閱識別碼

下列範例顯示擷 取單一檔的 JavaScript 函式 。 函式會由 HTTP 要求觸發，該 HTTP 要求會使用查詢字串指定要查閱的識別碼和分割區索引鍵值。 該識別碼和分割區索引鍵值會用來從指定的資料庫和集合中擷取 ToDoItem 文件。

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

HTTP 觸發程序，從路由資料中查閱識別碼

下列範例顯示擷 取單一檔的 JavaScript 函式 。 函式會由 HTTP 要求觸發，該 HTTP 要求會使用路由資料指定要查閱的識別碼和分割區索引鍵值。 該識別碼和分割區索引鍵值會用來從指定的資料庫和集合中擷取 ToDoItem 文件。

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

佇列觸發程序，使用 SqlQuery 取得多個文件

下列範例示範使用 佇列觸發程式來自定義查詢參數，擷取 SQL 查詢所指定的多個檔的 JavaScript 函 式。

佇列觸發程序會提供參數 departmentId。 { "departmentId" : "Finance" } 的佇列訊息會傳回財務部門的所有記錄。

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: (queueItem, context) => {
        const documents = context.extraInputs.get(cosmosInput);
        for (const document of documents) {
            // operate on each document
        }
    },
});

佇列觸發程式，從 JSON 查閱標識符

下列範例示範如何讀取和更新單一 Azure Cosmos DB 檔。 檔的唯一標識碼是透過佇列訊息中的 JSON 值來提供。

Azure Cosmos DB 輸入系結會先列在函式組態檔 （function.json） 中找到的系結清單中。

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

run.ps1 檔案具有 PowerShell 程式代碼，可讀取傳入的文件並輸出變更。

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document

HTTP 觸發程序，從查詢字串中查閱識別碼

下列範例示範如何從 Web API 讀取和更新單一 Azure Cosmos DB 檔。 檔的唯一標識碼是透過 HTTP 要求的 querystring 參數來提供，如系結的 "Id": "{Query.Id}" 屬性中所定義。

Azure Cosmos DB 輸入系結會先列在函式組態檔 （function.json） 中找到的系結清單中。

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
}

run.ps1 檔案具有 PowerShell 程式代碼，可讀取傳入的文件並輸出變更。

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

HTTP 觸發程序，從路由資料中查閱識別碼

下列範例示範如何從 Web API 讀取和更新單一 Azure Cosmos DB 檔。 檔的唯一標識碼是透過路由參數提供。 路由參數定義於 HTTP 要求系結的 屬性中 route ，並在 Azure Cosmos DB "Id": "{Id}" 系結屬性中參考。

Azure Cosmos DB 輸入系結會先列在函式組態檔 （function.json） 中找到的系結清單中。

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
}

run.ps1 檔案具有 PowerShell 程式代碼，可讀取傳入的文件並輸出變更。

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

佇列觸發程序，使用 SqlQuery 取得多個文件

下列範例示範如何讀取多個 Azure Cosmos DB 檔。 函式的組態檔 （function.json） 會定義系結屬性，其中包括 sqlQuery。 提供給 屬性的 sqlQuery SQL 語句會選取提供給 函式的檔集。

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
}

run1.ps1 檔案具有可讀取傳入檔的 PowerShell 程式代碼。

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
}

本節包含下列範例，這些範例會藉由指定來自各種來源的標識符值來讀取單一檔：

這些範例取決於您使用的是 v1 或 v2 Python 程式設計模型。

佇列觸發程式，從 JSON 查閱標識符

下列範例顯示 Azure Cosmos DB 輸入系結。 函式會讀取單一文件，並更新文件的文字值。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.queue_trigger(arg_name="msg", 
                   queue_name="outqueue", 
                   connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents", 
                     database_name="MyDatabase",
                     collection_name="MyCollection",
                     id="{msg.payload_property}",
                     partition_key="{msg.payload_property}",
                     connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument", 
                      database_name="MyDatabase",
                      collection_name="MyCollection",
                      connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
                  inputDocument: func.DocumentList, 
                  outputDocument: func.Out[func.Document]):
     document = documents[id]
     document["text"] = "This was updated!"
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

HTTP 觸發程序，從查詢字串中查閱識別碼

下列範例顯示擷取單一檔的函式。 函式會由 HTTP 要求觸發，該 HTTP 要求會使用查詢字串指定要查閱的識別碼和分割區索引鍵值。 該識別碼和分割區索引鍵值會用來從指定的資料庫和集合中擷取 ToDoItem 文件。

目前沒有 v2 的對等範例。

HTTP 觸發程序，從路由資料中查閱識別碼

下列範例顯示擷取單一檔的函式。 函式會由 HTTP 要求觸發，該 HTTP 要求會使用路由資料指定要查閱的識別碼和分割區索引鍵值。 該識別碼和分割區索引鍵值會用來從指定的資料庫和集合中擷取 ToDoItem 文件。

目前沒有 v2 的對等範例。

佇列觸發程序，使用 SqlQuery 取得多個文件

下列範例顯示使用系結的 Azure Cosmos DB 輸入系結 Python 函式。 函式會使用佇列觸發程序來自訂查詢參數，以擷取 SQL 查詢所指定的多份文件。

佇列觸發程序會提供參數 departmentId。 { "departmentId" : "Finance" } 的佇列訊息會傳回財務部門的所有記錄。

目前沒有 v2 的對等範例。

屬性

進程內和隔離的背景工作進程 C# 連結庫都會使用屬性來定義函式。 C# 文稿會改用function.json組態檔，如 C# 腳本指南中所述。

屬性內容 描述
[連接] 應用程式設定或設定集合的名稱，指定如何連線到要查詢的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
DatabaseName 該 Azure Cosmos DB 資料庫名稱含有要監視的容器。
ContainerName 要監視的容器名稱。
PartitionKey 指定分割區索引鍵值進行查閱。 可能包含繫結參數。 資料分割容器中的查閱是必要的。
Id 要擷取之文件的識別碼。 此屬性支援繫結運算式。 請勿同時設定 Id 和 SqlQuery 屬性。 如果您未設定其中一個，就會擷取整個容器。
SqlQuery 用來擷取多份文件的 Azure Cosmos DB SQL 查詢。 屬性會支援執行階段繫結，如此範例所示：SELECT * FROM c where c.departmentId = {departmentId}。 請勿同時設定 Id 和 SqlQuery 屬性。 如果您未設定其中一個，就會擷取整個容器。
PreferredLocations (選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如： East US,South Central US,North Europe 。

裝飾項目

僅適用於 Python v2 程式設計模型。

Python v2 函式是使用 cosmos_db_input 裝飾項目來定義，其支援這些屬性，視擴充功能版本而定：

屬性 說明
arg_name 函式程式碼中使用的變數名稱，代表有變更的文件清單。
database_name 受監視集合的 Azure Cosmos DB 資料庫名稱。
container_name 要監視的 Azure Cosmos DB 集合名稱。
connection 正在監視的 Azure Cosmos DB 連接字串。
partition_key 受監視之 Azure Cosmos DB 的數據分割索引鍵。
id 要擷取之文件的識別碼。

如需使用 function.json 定義的 Python 函式，請參閱組 態 一節。

註釋

從 Java 函式運行時間連結庫，對從 Azure Cosmos DB 讀取的參數使用@CosmosDBInput註釋。 註解支援下列屬性：

組態

僅適用於 Python v1 程式設計模型。

下表說明您可以在傳遞至 input.cosmosDB() 方法的物件options上設定的屬性。 type、 direction和 name 屬性不適用於 v4 模型。

下表說明您在 function.json 檔案中設定的系結組態屬性，其中屬性與延伸模組版本不同：

function.json 屬性 描述
type 必須設定為 cosmosDB。
direction 必須設定為 in。
name 函式程式碼中使用的變數名稱，代表有變更的文件清單。
connection 應用程式設定或設定容器的名稱，該名稱會指定如何連接到要監視的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
databaseName 該 Azure Cosmos DB 資料庫名稱含有要監視的容器。
containerName 要監視的容器名稱。
partitionKey 指定分割區索引鍵值進行查閱。 可能包含繫結參數。 資料分割容器中的查閱是必要的。
id 要擷取之文件的識別碼。 此屬性支援繫結運算式。 請勿同時設定 id 和 sqlQuery 屬性。 如果您未設定其中一個，就會擷取整個容器。
sqlQuery 用來擷取多份文件的 Azure Cosmos DB SQL 查詢。 屬性會支援執行階段繫結，如此範例所示：SELECT * FROM c where c.departmentId = {departmentId}。 請勿同時設定 id 和 sqlQuery 屬性。 如果您未設定其中一個，就會擷取整個容器。
preferredLocations (選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如： East US,South Central US,North Europe 。

如需完整範例，請參閱範例一節。

使用方式

當函式順利結束時，會自動保存對輸入檔所做的任何變更。

Cosmos DB 輸入系結所支持的參數類型取決於 Functions 運行時間版本、擴充套件版本，以及所使用的 C# 形式。

當您想要讓函式處理單一檔時，Cosmos DB 輸入系結可以繫結至下列類型：

類型 描述
JSON 可序列化型別 函式會嘗試將檔的 JSON 數據還原串行化為純舊 CLR 物件 （POCO） 類型。

當您要函式從查詢處理多個檔案時，Cosmos DB 輸入系結可以繫結至下列類型：

類型 描述
IEnumerable<T>其中 T 是 JSON 可串行化類型 查詢所傳回之實體的列舉。 每個專案都代表一份檔。
CosmosClient1 線上到 Cosmos DB 帳戶的用戶端。
資料庫1 線上至 Cosmos DB 資料庫的用戶端。
容器1 線上至 Cosmos DB 容器的用戶端。

1 若要使用這些類型，您必須參考 Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 或更新版本 ，以及 SDK 類型系結的常見相依性。

從 Java 函式運行時間連結庫，@CosmosDBInput註釋會將 Azure Cosmos DB 數據公開給函式。 此批注可以搭配原生 Java 類型、POJO 或使用 可為 Null 的值使用 Optional<T>。

使用 context.extraInputs.get()存取檔。

函式結束時，不會自動更新檔。 若要更新函式中的檔，請使用 輸出系結。 如需詳細資訊， 請參閱 PowerShell 範例 。

數據可透過 DocumentList 參數提供給函式。 對檔所做的變更不會自動保存。

連線

connectionStringSetting/connection和 leaseConnectionStringSetting/leaseConnection 屬性是環境組態的參考，其會指定應用程式應該如何連線到 Azure Cosmos DB。 他們可以指定：

如果設定的值與單一設定完全相符，又與其他設定的開頭相符，則會使用完全相符項目。

Connection string

資料庫帳戶的 連接字串 應該儲存在應用程式設定中，其名稱符合系結組態的連接屬性所指定的值。

身分識別型連線

如果您使用 4.x 版或更新版本的延伸模組，而不是使用具有秘密的 連接字串，您可以讓應用程式使用 Microsoft Entra 身分識別。 若要執行此動作，您會在觸發程序和繫結設定中對應至「連線」屬性的通用前置詞下定義設定。

在此模式中，延伸模組需要下列屬性：

屬性 環境變數範本 描述 範例值
帳戶端點 <CONNECTION_NAME_PREFIX>__accountEndpoint Azure Cosmos DB 帳戶端點 URI。 <https:// database_account_name.documents.azure.com:443/>

還可以設定其他屬性來自訂連線。 請參閱身分識別型連線的通用屬性。

主控於 Azure Functions 服務時，以身分識別為基礎的連接會使用受控識別。 雖然可以使用 credential 和 clientID 屬性指定使用者指派的身分識別，但預設會使用系統指派的身分識別。 請注意，不支援以資源識別碼來設定使用者指派的身分識別。 在本機開發等其他內容中執行時，雖然這可以自訂，但仍會改用您的開發人員身分識別。 請參閱使用身分識別型連線進行本機開發。

授與權限給身分識別

正在使用的任何身分識別，都必須具有執行預期動作的權限。 有關大多數 Azure 服務，意即您需要指派 Azure RBAC 的角色，利用提供這些權限的內建或自訂角色。

重要

部分權限可能會由所有內容都不需要的目標服務公開。 可以的話，請遵循最低權限原則，只授與身分識別所需的權限。 例如，如果應用程式只需要能夠讀取資料來源，請使用只有讀取權限的角色。 不宜指派也允許寫入該服務的角色，因為讀取作業不需要這麼多權限。 同樣地，最好確保角色指派的範圍僅限於需要讀取的資源。

Cosmos DB 不會針對資料作業使用 Azure RBAC。 反而會改用以類似概念為基礎的 Cosmos DB 內建 RBAC 系統。 您必須建立可在執行時間存取資料庫帳戶的角色指派。 擁有者等的 Azure RBAC 管理角色並不足夠。 下表會顯示通常作業中使用 Azure Cosmos DB 延伸模組時建議的內建角色。 您的應用程式可能會根據您寫入的程式碼要求額外的權限。

繫結類型 內建角色範例1
Trigger2 Cosmos DB 內建資料參與者
輸入繫結 Cosmos DB 內建資料讀取器
輸出繫結 Cosmos DB 內建資料參與者

1 這些角色無法用於 Azure RBAC 角色指派。 如需如何指派這些角色的詳細資訊，請參閱 Cosmos DB 內建 RBAC 系統文件。

2 使用身分識別時，Cosmos DB 會將容器建立視為管理作業。 其不可作為觸發程序的資料平面作業。 您必須確定在設定函式之前，先建立觸發程序所需的容器 (包括租用容器)。

下一步