Pengikatan input Azure Cosmos DB untuk Azure Functions 2.x dan yang lebih tinggi
Pengikatan input Azure Cosmos DB menggunakan SQL API untuk mengambil satu atau beberapa dokumen Azure Cosmos DB dan meneruskannya ke parameter input fungsi. ID dokumen atau parameter kueri dapat ditentukan berdasarkan pada pemicu yang memanggil fungsi.
Untuk informasi tentang pengaturan dan detail konfigurasi, lihat gambaran umum.
Catatan
Jika koleksi dipartisi, operasi pencarian juga harus menentukan nilai kunci partisi.
Penting
Artikel ini menggunakan tab untuk mendukung beberapa versi model pemrograman Node.js. Model v4 umumnya tersedia dan dirancang untuk memiliki pengalaman yang lebih fleksibel dan intuitif untuk pengembang JavaScript dan TypeScript. Untuk detail selengkapnya tentang cara kerja model v4, lihat panduan pengembang Node.js Azure Functions. Untuk mempelajari selengkapnya tentang perbedaan antara v3 dan v4, lihat panduan migrasi.
Azure Functions mendukung dua model pemrograman untuk Python. Cara Anda menentukan pengikatan tergantung pada model pemrograman yang Anda pilih.
Model pemrograman Python v2 memungkinkan Anda menentukan pengikatan menggunakan dekorator langsung dalam kode fungsi Python Anda. Untuk informasi selengkapnya, lihat panduan pengembang Python.
Artikel ini mendukung kedua model pemrograman.
Contoh
Kecuali dinyatakan lain, contoh pada artikel ini menargetkan versi 3.x dari ekstensi Azure Cosmos DB. Untuk digunakan bersama ekstensi versi 4.x, Anda perlu mengganti string collection
dalam properti dan nama atribut dengan container
.
Fungsi C# dapat dibuat dengan menggunakan salah satu mode C# berikut:
- Model pekerja terisolasi: Fungsi C# terkompilasi yang berjalan dalam proses pekerja yang terisolasi dari runtime. Proses pekerja terisolasi diperlukan untuk mendukung fungsi C# yang berjalan pada versi LTS dan non-LTS .NET dan .NET Framework. Ekstensi untuk fungsi proses pekerja yang terisolasi menggunakan
Microsoft.Azure.Functions.Worker.Extensions.*
namespace layanan. - Model dalam proses: Fungsi C# yang dikompilasi yang berjalan dalam proses yang sama dengan runtime Functions. Dalam variasi model ini, Functions dapat dijalankan menggunakan scripting C#, yang didukung terutama untuk pengeditan portal C#. Ekstensi untuk fungsi dalam proses menggunakan
Microsoft.Azure.WebJobs.Extensions.*
namespace layanan.
Penting
Dukungan akan berakhir untuk model dalam proses pada 10 November 2026. Kami sangat menyarankan Agar Anda memigrasikan aplikasi Anda ke model pekerja yang terisolasi untuk dukungan penuh.
Bagian ini berisi contoh yang memerlukan ekstensi Azure Cosmos DB versi 3.x dan ekstensi Azure Storage 5.x. Jika belum ada di aplikasi fungsi Anda, tambahkan referensi ke paket NuGet berikut:
Contohnya mengacu pada jenis ToDoItem
sederhana:
[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}");
}
}
Pemicu antrean, cari ID dari JSON
Contoh berikut memperlihatkan sebuah fungsi yang mengambil dokumen tunggal. Fungsi ini dipicu oleh pesan JSON dalam antrean penyimpanan. Pemicu antrean memilah JSON ke dalam objek jenis ToDoItemLookup
yang berisi ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi tersebut digunakan untuk mengambil ToDoItem
dokumen dari database dan kumpulan yang ditentukan.
[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}");
}
}
Bagian ini berisi contoh-contoh berikut:
- Pemicu HTTP, cari ID dari string kueri: Parameter string
- Pemicu HTTP, cari ID dari string kueri: Parameter POJO
- Pemicu HTTP, cari ID dari data rute
- Pemicu HTTP, cari ID dari data rute, menggunakan SqlQuery
- Pemicu HTTP, dapatkan beberapa dokumen dari data rute, menggunakan SqlQuery
Contohnya mengacu pada jenis ToDoItem
sederhana:
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 + "}";
}
}
Pemicu HTTP, cari ID dari string kueri: Parameter string
Contoh berikut memperlihatkan fungsi Java yang mengambil satu dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan string kueri untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi tersebut digunakan untuk mengambil dokumen dari database dan kumpulan yang ditentukan, dalam format 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();
}
}
}
Di pustaka runtime fungsi Java, gunakan @CosmosDBInput
anotasi pada parameter fungsi yang nilainya akan berasal dari Azure Cosmos DB. Anotasi ini dapat digunakan dengan jenis Java asli, POJO, atau nilai yang dapat diubah ke null menggunakan Optional<T>
.
Pemicu HTTP, cari ID dari string kueri: Parameter POJO
Contoh berikut memperlihatkan fungsi Java yang mengambil satu dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan string kueri untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi yang digunakan untuk mengambil dokumen dari database dan kumpulan yang ditentukan. Dokumen kemudian dikonversi menjadi instans ToDoItem
POJO yang sebelumnya dibuat, dan diteruskan sebagai argumen ke fungsi.
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();
}
}
}
Pemicu HTTP, cari ID dari data rute
Contoh berikut memperlihatkan fungsi Java yang mengambil satu dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan parameter rute untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi digunakan untuk mengambil dokumen dari database dan kumpulan yang ditentukan, dan mengembalikannya sebagai 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();
}
}
}
Pemicu HTTP, cari ID dari data rute, menggunakan SqlQuery
Contoh berikut memperlihatkan fungsi Java yang mengambil satu dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan parameter rute untuk menentukan ID untuk pencarian. ID tersebut digunakan untuk mengambil dokumen dari database dan kumpulan yang ditentukan, mengonversi hasil yang ditetapkan menjadi ToDoItem[]
, mengingat banyak dokumen dapat dikembalikan dan bergantung pada kriteria kueri.
Catatan
Jika Anda hanya perlu mengkueri ID, gunakan pencarian, seperti contoh sebelumnya, karena akan mengonsumsi lebih sedikit unit permintaan. Operasi baca titik (GET) lebih efisien daripada kueri berdasarkan ID.
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();
}
}
}
Pemicu HTTP, dapatkan beberapa dokumen dari data rute, menggunakan SqlQuery
Contoh berikut memperlihatkan fungsi Java yang mengambil beberapa dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan parameter rute desc
untuk menentukan string yang akan dicari di bidang description
. Istilah pencarian digunakan untuk mengambil kumpulan dokumen dari database dan kumpulan yang ditentukan, mengonversi hasil menjadi ToDoItem[]
dan meneruskannya sebagai argumen ke fungsi.
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();
}
}
}
Bagian ini menyediakan contoh-contoh yang membaca satu dokumen dengan menentukan nilai ID dari berbagai sumber:
- Pemicu antrean, cari ID dari JSON
- Pemicu HTTP, cari ID dari string kueri
- Pemicu HTTP, cari ID dari data rute
- Pemicu antrean, dapatkan beberapa dokumen, menggunakan SqlQuery
Pemicu antrean, cari ID dari JSON
Contoh berikut menunjukkan fungsi TypeScript yang membaca satu dokumen dan memperbarui nilai teks dokumen.
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,
});
Pemicu HTTP, cari ID dari string kueri
Contoh berikut menunjukkan fungsi TypeScript yang mengambil satu dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan string kueri untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi tersebut digunakan untuk mengambil ToDoItem
dokumen dari database dan kumpulan yang ditentukan.
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,
});
Pemicu HTTP, cari ID dari data rute
Contoh berikut menunjukkan fungsi TypeScript yang mengambil satu dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan data rute untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi tersebut digunakan untuk mengambil ToDoItem
dokumen dari database dan kumpulan yang ditentukan.
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,
});
Pemicu antrean, dapatkan beberapa dokumen, menggunakan SqlQuery
Contoh berikut menunjukkan fungsi TypeScript yang mengambil beberapa dokumen yang ditentukan oleh kueri SQL, menggunakan pemicu antrean untuk mengkustomisasi parameter kueri.
Pemicu antrean menyediakan parameter departmentId
. Pesan antrean { "departmentId" : "Finance" }
akan mengembalikan semua catatan untuk departemen keuangan.
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,
});
Bagian ini menyediakan contoh-contoh yang membaca satu dokumen dengan menentukan nilai ID dari berbagai sumber:
- Pemicu antrean, cari ID dari JSON
- Pemicu HTTP, cari ID dari string kueri
- Pemicu HTTP, cari ID dari data rute
- Pemicu antrean, dapatkan beberapa dokumen, menggunakan SqlQuery
Pemicu antrean, cari ID dari JSON
Contoh berikut menunjukkan fungsi JavaScript yang membaca satu dokumen dan memperbarui nilai teks dokumen.
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);
},
});
Pemicu HTTP, cari ID dari string kueri
Contoh berikut memperlihatkan fungsi JavaScript yang mengambil satu dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan string kueri untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi tersebut digunakan untuk mengambil ToDoItem
dokumen dari database dan kumpulan yang ditentukan.
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}`,
};
}
},
});
Pemicu HTTP, cari ID dari data rute
Contoh berikut memperlihatkan fungsi JavaScript yang mengambil satu dokumen. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan data rute untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi tersebut digunakan untuk mengambil ToDoItem
dokumen dari database dan kumpulan yang ditentukan.
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}`,
};
}
},
});
Pemicu antrean, dapatkan beberapa dokumen, menggunakan SqlQuery
Contoh berikut menunjukkan fungsi JavaScript yang mengambil beberapa dokumen yang ditentukan oleh kueri SQL, menggunakan pemicu antrean untuk menyesuaikan parameter kueri.
Pemicu antrean menyediakan parameter departmentId
. Pesan antrean { "departmentId" : "Finance" }
akan mengembalikan semua catatan untuk departemen keuangan.
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
}
},
});
- Pemicu antrean, cari ID dari JSON
- Pemicu HTTP, cari ID dari string kueri
- Pemicu HTTP, cari ID dari data rute
- Pemicu antrean, dapatkan beberapa dokumen, menggunakan SqlQuery
Pemicu antrean, cari ID dari JSON
Contoh berikut menunjukkan cara membaca dan memperbarui satu dokumen Azure Cosmos DB. Pengidentifikasi unik dokumen disediakan melalui nilai JSON dalam pesan antrean.
Pengikatan input Azure Cosmos DB tercantum terlebih dahulu dalam daftar pengikatan yang ditemukan dalam file konfigurasi fungsi (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"
}
File run.ps1 memiliki kode PowerShell yang membaca dokumen masuk dan perubahan output.
param($QueueItem, $InputDocumentIn, $TriggerMetadata)
$Document = $InputDocumentIn
$Document.text = 'This was updated!'
Push-OutputBinding -Name InputDocumentOut -Value $Document
Pemicu HTTP, cari ID dari string kueri
Contoh berikut menunjukkan cara membaca dan memperbarui satu dokumen Azure Cosmos DB dari API web. Pengidentifikasi unik dokumen disediakan melalui parameter querystring dari permintaan HTTP, seperti yang didefinisikan dalam properti pengikatan "Id": "{Query.Id}"
.
Pengikatan input Azure Cosmos DB tercantum terlebih dahulu dalam daftar pengikatan yang ditemukan dalam file konfigurasi fungsi (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
}
File run.ps1 memiliki kode PowerShell yang membaca dokumen masuk dan perubahan output.
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
})
}
Pemicu HTTP, cari ID dari data rute
Contoh berikut menunjukkan cara membaca dan memperbarui satu dokumen Azure Cosmos DB dari API web. Pengidentifikasi unik dokumen disediakan melalui parameter rute. Parameter rute ditentukan dalam properti pengikatan route
permintaan HTTP dan dirujuk di properti pengikatan Azure Cosmos DB "Id": "{Id}"
.
Pengikatan input Azure Cosmos DB tercantum terlebih dahulu dalam daftar pengikatan yang ditemukan dalam file konfigurasi fungsi (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
}
File run.ps1 memiliki kode PowerShell yang membaca dokumen masuk dan perubahan output.
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
})
}
Pemicu antrean, dapatkan beberapa dokumen, menggunakan SqlQuery
Contoh berikut menunjukkan cara membaca beberapa dokumen Azure Cosmos DB. File konfigurasi fungsi (function.json) mendefinisikan properti pengikatan, yang mencakup sqlQuery
. Pernyataan SQL yang diberikan ke properti sqlQuery
memilih sekumpulan dokumen yang disediakan untuk fungsi tersebut.
{
"name": "Documents",
"type": "cosmosDB",
"direction": "in",
"databaseName": "MyDb",
"collectionName": "MyCollection",
"sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
"connectionStringSetting": "CosmosDBConnection"
}
File run1.ps1 memiliki kode PowerShell yang membaca dokumen masuk.
param($QueueItem, $Documents, $TriggerMetadata)
foreach ($Document in $Documents) {
# operate on each document
}
Bagian ini menyediakan contoh-contoh yang membaca satu dokumen dengan menentukan nilai ID dari berbagai sumber:
- Pemicu antrean, cari ID dari JSON
- Pemicu HTTP, cari ID dari string kueri
- Pemicu HTTP, cari ID dari data rute
- Pemicu antrean, dapatkan beberapa dokumen, menggunakan SqlQuery
Contohnya bergantung pada apakah Anda menggunakan model pemrograman Python v1 atau v2.
Pemicu antrean, cari ID dari JSON
Contoh berikut menunjukkan pengikatan input Azure Cosmos DB. Fungsi ini membaca satu dokumen dan memperbarui nilai teks dokumen.
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.")
Pemicu HTTP, cari ID dari string kueri
Contoh berikut memperlihatkan sebuah fungsi yang mengambil dokumen tunggal. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan string kueri untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi tersebut digunakan untuk mengambil ToDoItem
dokumen dari database dan kumpulan yang ditentukan.
Pemicu HTTP, cari ID dari data rute
Contoh berikut memperlihatkan sebuah fungsi yang mengambil dokumen tunggal. Fungsi ini dipicu oleh permintaan HTTP yang menggunakan data rute untuk menentukan ID dan nilai kunci partisi untuk pencarian. ID dan nilai kunci partisi tersebut digunakan untuk mengambil ToDoItem
dokumen dari database dan kumpulan yang ditentukan.
Pemicu antrean, dapatkan beberapa dokumen, menggunakan SqlQuery
Contoh berikut menunjukkan fungsi Python pengikatan input Azure Cosmos DB yang menggunakan pengikatan. Fungsi ini mengambil beberapa dokumen yang ditentukan oleh kueri SQL, menggunakan pemicu antrean untuk menyesuaikan parameter kueri.
Pemicu antrean menyediakan parameter departmentId
. Pesan antrean { "departmentId" : "Finance" }
akan mengembalikan semua catatan untuk departemen keuangan.
Atribut
Pustaka C# proses dalam proses dan terisolasi menggunakan atribut untuk menentukan fungsi. Skrip C# sebagai gantinya menggunakan file konfigurasi function.json seperti yang dijelaskan dalam panduan pembuatan skrip C#.
Properti atribut | Deskripsi |
---|---|
Koneksi | Nama pengaturan aplikasi atau koleksi aplikasi yang menentukan cara terhubung pada akun Azure Cosmos DB yang sedang dipantau. Untuk informasi selengkapnya, lihat Sambungan. |
DatabaseName | Nama database Azure Cosmos DB dengan koleksi sedang dalam pemantauan. |
ContainerName | Nama kontainer yang sedang dipantau. |
PartitionKey | Menentukan nilai kunci partisi untuk pencarian. Mungkin termasuk parameter pengikatan. Diperlukan bagi pencarian dalam koleksi yang dipartisi. |
Id | ID dokumen yang akan diambil. Properti ini mendukung ekspresi pengikatan. Jangan atur properti Id dan SqlQuery . Jika Anda tidak menyetel salah satu koleksi, seluruh koleksi akan diambil. |
SqlQuery | Kueri SQL Azure Cosmos DB digunakan untuk mengambil beberapa dokumen. Properti mendukung pengikatan runtime, seperti dalam contoh ini: SELECT * FROM c where c.departmentId = {departmentId} . Jangan atur properti Id dan SqlQuery . Jika Anda tidak menyetel salah satu koleksi, seluruh koleksi akan diambil. |
PreferredLocations | (Opsional) Menentukan lokasi (wilayah) pilihan untuk akun database yang direplikasi geografis di layanan Azure Cosmos DB. Nilai harus dipisahkan koma. Contohnya,East US,South Central US,North Europe . |
Dekorator
Hanya berlaku untuk model pemrograman Python v2.
Fungsi Python v2 didefinisikan menggunakan cosmos_db_input
dekorator, yang mendukung properti ini, tergantung pada versi ekstensi:
Properti | Deskripsi |
---|---|
arg_name |
Nama variabel yang digunakan dalam kode fungsi yang mewakili daftar dokumen dengan perubahan. |
database_name |
Nama database Azure Cosmos DB dengan koleksi sedang dipantau. |
container_name |
Nama koleksi Azure Cosmos DB yang sedang dipantau. |
connection |
String koneksi Azure Cosmos DB yang sedang dipantau. |
partition_key |
Kunci partisi Azure Cosmos DB sedang dipantau. |
id |
ID dokumen yang akan diambil. |
Untuk fungsi Python yang ditentukan dengan menggunakan function.json, lihat bagian Konfigurasi .
Anotasi
Dari pustaka runtime fungsi Java, gunakan anotasi @CosmosDBInput
pada parameter yang membaca data dari Cosmos DB. Anotasi mendukung properti berikut ini:
Konfigurasi
Hanya berlaku untuk model pemrograman Python v1.
Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json, di mana properti berbeda menurut versi ekstensinya:
Properti function.json | Deskripsi |
---|---|
jenis | Harus diatur ke cosmosDB . |
arah | Harus diatur ke in . |
nama | Nama variabel yang digunakan dalam kode fungsi yang mewakili daftar dokumen dengan perubahan. |
koneksi | Nama pengaturan aplikasi atau koleksi aplikasi yang menentukan cara tersambung ke akun Azure Cosmos DB yang sedang dipantau. Untuk informasi selengkapnya, lihat Sambungan. |
databaseName | Nama database Azure Cosmos DB dengan koleksi sedang dalam pemantauan. |
containerName | Nama kontainer yang sedang dipantau. |
partitionKey | Menentukan nilai kunci partisi untuk pencarian. Mungkin termasuk parameter pengikatan. Diperlukan bagi pencarian dalam koleksi yang dipartisi. |
id | ID dokumen yang akan diambil. Properti ini mendukung ekspresi pengikatan. Jangan atur properti id dan sqlQuery . Jika Anda tidak menyetel salah satu koleksi, seluruh koleksi akan diambil. |
sqlQuery | Kueri SQL Azure Cosmos DB digunakan untuk mengambil beberapa dokumen. Properti mendukung pengikatan runtime, seperti dalam contoh ini: SELECT * FROM c where c.departmentId = {departmentId} . Jangan atur properti id dan sqlQuery . Jika Anda tidak menyetel salah satu koleksi, seluruh koleksi akan diambil. |
preferredLocations | (Opsional) Menentukan lokasi (wilayah) pilihan untuk akun database yang direplikasi geografis di layanan Azure Cosmos DB. Nilai harus dipisahkan koma. Contohnya,East US,South Central US,North Europe . |
Lihat Bagian contoh untuk contoh lengkapnya.
Penggunaan
Ketika fungsi berhasil keluar, setiap perubahan pada dokumen input melalui parameter input bernama secara otomatis akan tetap ada.
Jenis parameter yang didukung oleh pengikatan input Cosmos DB tergantung pada versi runtime Functions, versi paket ekstensi, dan modalitas C# yang digunakan.
Saat Anda ingin fungsi memproses satu dokumen, pengikatan input Cosmos DB dapat mengikat ke jenis berikut:
Tipe | Deskripsi |
---|---|
Jenis yang bisa diserialisasikan JSON | Fungsi mencoba mendeserialisasi data JSON dokumen ke dalam jenis objek CLR (POCO) yang sudah lama biasa. |
Saat Anda ingin fungsi memproses beberapa dokumen dari kueri, pengikatan input Cosmos DB dapat mengikat ke jenis berikut:
Tipe | Deskripsi |
---|---|
IEnumerable<T> di mana T adalah jenis JSON yang dapat diserialisasikan |
Enumerasi entitas yang dikembalikan oleh kueri. Setiap entri mewakili satu dokumen. |
CosmosClient1 | Klien yang terhubung ke akun Cosmos DB. |
Database1 | Klien yang terhubung ke database Cosmos DB. |
Kontainer1 | Klien yang terhubung ke kontainer Cosmos DB. |
1 Untuk menggunakan jenis ini, Anda perlu mereferensikan Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 atau yang lebih baru dan dependensi umum untuk pengikatan jenis SDK.
Dari pustaka runtime fungsi Java, anotasi @CosmosDBInput mengekspos data Azure Cosmos DB ke fungsi . Anotasi ini dapat digunakan dengan jenis Java asli, POJO, atau nilai yang dapat diubah ke null menggunakan Optional<T>
.
Pembaruan untuk dokumen tidak otomatis dibuat setelah fungsi keluar. Untuk memperbarui dokumen di fungsi, gunakan pengikatan output. Lihat contoh PowerShell untuk detail selengkapnya.
Data tersedia untuk fungsi melalui parameter DocumentList
. Perubahan yang dilakukan pada dokumen tidak otomatis berlanjut.
Koneksi
Properti connectionStringSetting
/connection
dan leaseConnectionStringSetting
/leaseConnection
adalah referensi ke konfigurasi lingkungan yang menentukan cara aplikasi akan terhubung ke Azure Cosmos DB. Properti ini mungkin menentukan:
- Nama pengaturan aplikasi yang berisi string koneksi
- Nama awalan bersama untuk beberapa pengaturan aplikasi, bersama-sama menentukan koneksi berbasis identitas. Opsi ini hanya tersedia untuk versi
connection
danleaseConnection
dari ekstensi versi 4.x atau yang lebih tinggi.
Jika nilai yang dikonfigurasi adalah kecocokan persis untuk pengaturan tunggal dan kecocokan awalan untuk pengaturan lainnya, kecocokan persis akan digunakan.
String koneksi
String koneksi untuk akun database Anda harus disimpan dalam pengaturan aplikasi dengan nama yang cocok dengan nilai yang ditentukan oleh properti koneksi dari konfigurasi pengikatan.
Koneksi berbasis identitas
Jika Anda menggunakan ekstensi versi 4.x atau yang lebih tinggi, alih-alih menggunakan string koneksi dengan rahasia, Anda dapat meminta aplikasi menggunakan identitas Microsoft Entra. Untuk melakukannya, Anda akan menentukan pengaturan dengan awalan umum yang dipetakan ke properti koneksi dalam pemicu dan konfigurasi pengikatan.
Dalam mode ini, ekstensi tersebut memerlukan properti berikut:
Properti | Templat variabel lingkungan | Deskripsi | Contoh nilai |
---|---|---|---|
Titik Akhir Akun | <CONNECTION_NAME_PREFIX>__accountEndpoint |
URI titik akhir akun Azure Cosmos DB. | https://<database_account_name>.documents.azure.com:443/ |
Properti tambahan dapat diatur untuk menyesuaikan koneksi. Lihat Properti umum untuk koneksi berbasis identitas.
Saat dihosting di layanan Azure Functions, koneksi berbasis identitas menggunakan identitas terkelola. Identitas yang ditetapkan sistem digunakan secara default, meskipun identitas yang ditetapkan pengguna dapat ditentukan dengan credential
dan clientID
properti. Perhatikan bahwa mengonfigurasi identitas yang ditetapkan oleh pengguna dengan ID sumber daya tidak didukung. Saat dijalankan dalam konteks lain, seperti pengembangan lokal, identitas pengembang Anda digunakan sebagai gantinya, meskipun ini dapat dikustomisasi. Lihat Pengembangan lokal dengan koneksi berbasis identitas.
Memberikan izin kepada identitas
Identitas apa pun yang digunakan harus memiliki izin untuk melakukan tindakan yang dimaksudkan. Untuk sebagian besar layanan Azure, ini berarti Anda perlu menetapkan peran di Azure RBAC, menggunakan peran bawaan atau kustom yang menyediakan izin tersebut.
Penting
Beberapa izin mungkin diekspos oleh layanan target yang tidak diperlukan untuk semua konteks. Jika memungkinkan, patuhi prinsip hak istimewa paling rendah, dengan memberikan identitas hanya hak istimewa yang diperlukan. Misalnya, jika aplikasi hanya perlu dapat membaca dari sumber data, gunakan peran yang hanya memiliki izin untuk membaca. Tidak pantas untuk menetapkan peran yang juga memungkinkan menulis ke layanan itu, karena ini akan menjadi izin yang berlebihan untuk operasi baca. Demikian pula, Anda ingin memastikan penetapan peran hanya mencakup sumber daya yang perlu dibaca.
Cosmos DB tidak menggunakan Azure RBAC untuk operasi data. Sebaliknya, ia menggunakan sistem RBAC bawaan Cosmos DB yang dibangun berdasarkan konsep serupa. Anda perlu membuat penetapan peran yang menyediakan akses ke akun database Anda saat runtime. Peran Azure RBAC Management seperti Pemilik tidak cukup. Tabel berikut ini memperlihatkan peran bawaan yang direkomendasikan saat menggunakan ekstensi Azure Cosmos DB dalam operasi normal. Aplikasi Anda mungkin memerlukan izin tambahan berdasarkan kode yang Anda tulis.
Jenis pengikatan | Contoh peran bawaan1 |
---|---|
Pemicu2 | Kontributor Data Bawaan Cosmos DB |
Pengikatan masukan | Pembaca Data Bawaan Cosmos DB |
Pengikatan output | Kontributor Data Bawaan Cosmos DB |
1 Peran ini tidak dapat digunakan dalam penetapan peran Azure RBAC. Lihat dokumentasi sistem RBAC bawaan Cosmos DB untuk detail tentang cara menetapkan peran ini.
2 Saat menggunakan identitas, Cosmos DB memperlakukan pembuatan kontainer sebagai operasi manajemen. Ini tidak tersedia sebagai operasi data-plane untuk pemicu. Anda harus memastikan bahwa Anda membuat kontainer yang diperlukan oleh pemicu (termasuk kontainer sewa) sebelum menyiapkan fungsi Anda.