Azure Cosmos DB bemeneti kötés az Azure Functions 2.x és újabb verzióihoz
Az Azure Cosmos DB bemeneti adatkötése az SQL API-t használja egy vagy több Azure Cosmos DB-dokumentum lekérésére, majd átadja ezeket a függvény bemeneti paraméterének. A dokumentumazonosítót vagy lekérdezési paramétereket a függvényt meghívó eseményindító alapján alapján lehet meghatározni.
A beállítással és a konfigurációval kapcsolatos információkért tekintse meg az áttekintést.
Feljegyzés
A gyűjtemény particionálásakor a keresési műveleteknek meg kell adniuk a partíciókulcs értékét is.
Fontos
Ez a cikk lapokat használ a Node.js programozási modell több verziójának támogatásához. A v4-modell általánosan elérhető, és úgy lett kialakítva, hogy rugalmasabb és intuitívabb felhasználói élményt nyújtson JavaScript- és TypeScript-fejlesztők számára. A v4-modell működésével kapcsolatos további információkért tekintse meg az Azure Functions Node.js fejlesztői útmutatóját. A v3 és a v4 közötti különbségekről a migrálási útmutatóban olvashat bővebben.
Az Azure Functions két Python-programozási modellt támogat. A kötések definiálásának módja a választott programozási modelltől függ.
A Python v2 programozási modell lehetővé teszi, hogy a kötéseket dekorátorokkal definiálja közvetlenül a Python-függvénykódban. További információt a Python fejlesztői útmutatójában talál.
Ez a cikk mindkét programozási modellt támogatja.
Példa
Ha másként nem jelezzük, a cikkben szereplő példák az Azure Cosmos DB-bővítmény 3.x-es verzióját célják. A 4.x-es verziójú bővítményhez a tulajdonság- és attribútumnevek sztringje collection
helyett a következőt container
kell használnia: .
A C#-függvények a következő C#-módok egyikével hozhatók létre:
- Izolált feldolgozómodell: Lefordított C# függvény, amely a futtatókörnyezettől elkülönített feldolgozói folyamatban fut. Izolált feldolgozói folyamat szükséges az LTS- és nem LTS-verziókon futó C#-függvények támogatásához .NET és .NET-keretrendszer. Az izolált feldolgozói folyamatfüggvények bővítményei névtereket használnak
Microsoft.Azure.Functions.Worker.Extensions.*
. - Folyamaton belüli modell: Lefordított C# függvény, amely ugyanabban a folyamatban fut, mint a Functions-futtatókörnyezet. A modell egy változatában a Functions C#-szkriptekkel futtatható, amely elsősorban a C#-portál szerkesztéséhez támogatott. A folyamaton belüli függvények bővítményei névtereket használnak
Microsoft.Azure.WebJobs.Extensions.*
.
Fontos
A folyamaton belüli modell támogatása 2026. november 10-én megszűnik. Erősen javasoljuk, hogy az alkalmazásokat az elkülönített feldolgozói modellbe migrálja a teljes támogatás érdekében.
Ez a szakasz olyan példákat tartalmaz, amelyekhez az Azure Cosmos DB-bővítmény 3.x-es verziója és az Azure Storage-bővítmény 5.x-es verziója szükséges. Ha még nincs jelen a függvényalkalmazásban, adjon hozzá hivatkozást a következő NuGet-csomagokhoz:
A példák egy egyszerű ToDoItem
típusra vonatkoznak:
[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}");
}
}
Üzenetsor-eseményindító, azonosító keresése a JSON-ból
Az alábbi példa egy olyan függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy JSON-üzenet aktiválja a tárolási üzenetsorban. Az üzenetsor-eseményindító a JSON-t egy olyan típusú ToDoItemLookup
objektumba elemzi, amely tartalmazza a lekérni kívánt azonosítót és partíciókulcs-értéket. Az azonosító és a partíciókulcs értéke a megadott adatbázisból és gyűjteményből származó dokumentum visszaadására ToDoItem
szolgál.
[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}");
}
}
Ez a szakasz a következő példákat tartalmazza:
- HTTP-eseményindító, azonosító keresése lekérdezési sztringből – Sztringparaméter
- HTTP-eseményindító, azonosító keresése lekérdezési sztringből – POJO paraméter
- HTTP-eseményindító, azonosító keresése útvonaladatokból
- HTTP-eseményindító, azonosító keresése útvonaladatokból az SqlQuery használatával
- HTTP-eseményindító, több dokumentum lekérése útvonaladatokból az SqlQuery használatával
A példák egy egyszerű ToDoItem
típusra vonatkoznak:
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-eseményindító, azonosító keresése lekérdezési sztringből – Sztringparaméter
Az alábbi példa egy Java-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. Ez az azonosító- és partíciókulcs-érték a megadott adatbázisból és gyűjteményből származó dokumentum sztring formátumú lekérésére szolgál.
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();
}
}
}
A Java-függvények futtatókörnyezeti kódtárában használja a jegyzetet olyan @CosmosDBInput
függvényparamétereken, amelyek értéke az Azure Cosmos DB-ből származna. Ez a széljegyzet natív Java-típusokkal, POJ-kkal vagy null értékű értékekkel használható a használatával Optional<T>
.
HTTP-eseményindító, azonosító keresése lekérdezési sztringből – POJO paraméter
Az alábbi példa egy Java-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. A dokumentumnak a megadott adatbázisból és gyűjteményből való lekéréséhez használt azonosító- és partíciókulcs-érték. A dokumentum ezután konvertálódik a ToDoItem
korábban létrehozott POJO-példányra, és argumentumként továbbítja a függvénynek.
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-eseményindító, azonosító keresése útvonaladatokból
Az alábbi példa egy Java-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely egy útvonalparamétert használ a kereséshez szükséges azonosító és partíciókulcs értékének megadásához. Ez az azonosító- és partíciókulcs-érték egy dokumentum lekérésére szolgál a megadott adatbázisból és gyűjteményből, és visszaadja azt 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-eseményindító, azonosító keresése útvonaladatokból az SqlQuery használatával
Az alábbi példa egy Java-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely egy útvonalparaméter használatával adja meg a megkeresendő azonosítót. Ez az azonosító egy dokumentum lekérésére szolgál a megadott adatbázisból és gyűjteményből, és az eredményhalmazt átalakítja egy ToDoItem[]
, mivel a lekérdezési feltételektől függően számos dokumentum visszaadható.
Feljegyzés
Ha csak az azonosító alapján kell lekérdeznie, javasoljuk, hogy az előző példákhoz hasonlóan keressen fel egy pillantást, mivel kevesebb kérelemegységet fog használni. A pontolvasási műveletek (GET) hatékonyabbak, mint az azonosító szerinti lekérdezések.
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-eseményindító, több dokumentum lekérése útvonaladatokból az SqlQuery használatával
Az alábbi példa egy Java-függvényt mutat be, amely több dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely egy útvonalparaméter desc
használatával adja meg a mezőben keresni description
kívánt sztringet. A keresési kifejezés dokumentumgyűjtemény lekérésére szolgál a megadott adatbázisból és gyűjteményből, átalakítja az eredményhalmazt egy ToDoItem[]
értékre, és argumentumként továbbítja azt a függvénynek.
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();
}
}
}
Ez a szakasz a következő példákat tartalmazza, amelyek egyetlen dokumentumot olvasnak egy azonosító értékének megadásával különböző forrásokból:
- Üzenetsor-eseményindító, azonosító keresése a JSON-ból
- HTTP-eseményindító, azonosító keresése lekérdezési sztringből
- HTTP-eseményindító, azonosító keresése útvonaladatokból
- Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával
Üzenetsor-eseményindító, azonosító keresése a JSON-ból
Az alábbi példa egy TypeScript-függvényt mutat be, amely egyetlen dokumentumot olvas be, és frissíti a dokumentum szöveges értékét.
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-eseményindító, azonosító keresése lekérdezési sztringből
Az alábbi példa egy TypeScript-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem
a megadott adatbázisból és gyűjteményből.
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-eseményindító, azonosító keresése útvonaladatokból
Az alábbi példa egy TypeScript-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely útvonaladatokat használ a megkeresendő azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem
a megadott adatbázisból és gyűjteményből.
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,
});
Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával
Az alábbi példa egy TypeScript-függvényt mutat be, amely egy SQL-lekérdezés által megadott több dokumentumot kér le egy üzenetsor-eseményindító használatával a lekérdezési paraméterek testreszabásához.
Az üzenetsor-eseményindító egy paramétert departmentId
biztosít. Egy üzenetsor { "departmentId" : "Finance" }
a pénzügyi részleg összes rekordját visszaadja.
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,
});
Ez a szakasz a következő példákat tartalmazza, amelyek egyetlen dokumentumot olvasnak egy azonosító értékének megadásával különböző forrásokból:
- Üzenetsor-eseményindító, azonosító keresése a JSON-ból
- HTTP-eseményindító, azonosító keresése lekérdezési sztringből
- HTTP-eseményindító, azonosító keresése útvonaladatokból
- Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával
Üzenetsor-eseményindító, azonosító keresése a JSON-ból
Az alábbi példa egy JavaScript-függvényt mutat be, amely egyetlen dokumentumot olvas be, és frissíti a dokumentum szöveges értékét.
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-eseményindító, azonosító keresése lekérdezési sztringből
Az alábbi példa egy JavaScript-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem
a megadott adatbázisból és gyűjteményből.
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-eseményindító, azonosító keresése útvonaladatokból
Az alábbi példa egy JavaScript-függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely útvonaladatokat használ a megkeresendő azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem
a megadott adatbázisból és gyűjteményből.
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}`,
};
}
},
});
Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával
Az alábbi példa egy JavaScript-függvényt mutat be, amely egy SQL-lekérdezés által megadott több dokumentumot kér le egy üzenetsor-eseményindító használatával a lekérdezési paraméterek testreszabásához.
Az üzenetsor-eseményindító egy paramétert departmentId
biztosít. Egy üzenetsor { "departmentId" : "Finance" }
a pénzügyi részleg összes rekordját visszaadja.
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
}
},
});
- Üzenetsor-eseményindító, azonosító keresése a JSON-ból
- HTTP-eseményindító, azonosító keresése lekérdezési sztringből
- HTTP-eseményindító, azonosító keresése útvonaladatokból
- Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával
Üzenetsor-eseményindító, azonosító keresése a JSON-ból
Az alábbi példa bemutatja, hogyan olvashat és frissíthet egyetlen Azure Cosmos DB-dokumentumot. A dokumentum egyedi azonosítója egy üzenetsor JSON-értékén keresztül van megadva.
Az Azure Cosmos DB bemeneti kötése először szerepel a függvény konfigurációs fájljában (function.json) található kötések listájában.
{
"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"
}
A run.ps1 fájl rendelkezik a PowerShell-kóddal, amely beolvassa a bejövő dokumentumot és a kimenet módosításait.
param($QueueItem, $InputDocumentIn, $TriggerMetadata)
$Document = $InputDocumentIn
$Document.text = 'This was updated!'
Push-OutputBinding -Name InputDocumentOut -Value $Document
HTTP-eseményindító, azonosító keresése lekérdezési sztringből
Az alábbi példa bemutatja, hogyan olvashat és frissíthet egyetlen Azure Cosmos DB-dokumentumot egy webes API-ból. A dokumentum egyedi azonosítóját a HTTP-kérés lekérdezési paramétere "Id": "{Query.Id}"
adja meg, a kötés tulajdonságában meghatározott módon.
Az Azure Cosmos DB bemeneti kötése először szerepel a függvény konfigurációs fájljában (function.json) található kötések listájában.
{
"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
}
A run.ps1 fájl rendelkezik a PowerShell-kóddal, amely beolvassa a bejövő dokumentumot és a kimenet módosításait.
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-eseményindító, azonosító keresése útvonaladatokból
Az alábbi példa bemutatja, hogyan olvashat és frissíthet egyetlen Azure Cosmos DB-dokumentumot egy webes API-ból. A dokumentum egyedi azonosítója egy útvonalparaméteren keresztül van megadva. Az útvonalparaméter a HTTP-kérelemkötés route
tulajdonságában van definiálva, és az Azure Cosmos DB "Id": "{Id}"
kötéstulajdonságában hivatkozik rá.
Az Azure Cosmos DB bemeneti kötése először szerepel a függvény konfigurációs fájljában (function.json) található kötések listájában.
{
"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
}
A run.ps1 fájl rendelkezik a PowerShell-kóddal, amely beolvassa a bejövő dokumentumot és a kimenet módosításait.
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
})
}
Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával
Az alábbi példa bemutatja, hogyan olvashat több Azure Cosmos DB-dokumentumot. A függvény konfigurációs fájlja (function.json) határozza meg a kötés tulajdonságait, beleértve a sqlQuery
. A tulajdonsághoz sqlQuery
megadott SQL-utasítás kiválasztja a függvénynek biztosított dokumentumokat.
{
"name": "Documents",
"type": "cosmosDB",
"direction": "in",
"databaseName": "MyDb",
"collectionName": "MyCollection",
"sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
"connectionStringSetting": "CosmosDBConnection"
}
A run1.ps1 fájl rendelkezik a bejövő dokumentumokat beolvasó PowerShell-kóddal.
param($QueueItem, $Documents, $TriggerMetadata)
foreach ($Document in $Documents) {
# operate on each document
}
Ez a szakasz a következő példákat tartalmazza, amelyek egyetlen dokumentumot olvasnak egy azonosító értékének megadásával különböző forrásokból:
- Üzenetsor-eseményindító, azonosító keresése a JSON-ból
- HTTP-eseményindító, azonosító keresése lekérdezési sztringből
- HTTP-eseményindító, azonosító keresése útvonaladatokból
- Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával
A példák attól függenek, hogy a v1 vagy v2 Python programozási modellt használja-e.
Üzenetsor-eseményindító, azonosító keresése a JSON-ból
Az alábbi példa egy Azure Cosmos DB bemeneti kötést mutat be. A függvény egyetlen dokumentumot olvas be, és frissíti a dokumentum szöveges értékét.
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-eseményindító, azonosító keresése lekérdezési sztringből
Az alábbi példa egy olyan függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely lekérdezési sztringet használ a kereséshez használt azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem
a megadott adatbázisból és gyűjteményből.
HTTP-eseményindító, azonosító keresése útvonaladatokból
Az alábbi példa egy olyan függvényt mutat be, amely egyetlen dokumentumot kér le. A függvényt egy HTTP-kérés aktiválja, amely útvonaladatokat használ a megkeresendő azonosító és partíciókulcs értékének megadásához. Ezzel az azonosítóval és partíciókulcs-értékkel kér le egy dokumentumot ToDoItem
a megadott adatbázisból és gyűjteményből.
Üzenetsor-eseményindító, több dokumentum lekérése az SqlQuery használatával
Az alábbi példa egy, a kötést használó Azure Cosmos DB bemeneti kötésű Python-függvényt mutat be. A függvény egy SQL-lekérdezés által megadott több dokumentumot kér le egy üzenetsor-eseményindító használatával a lekérdezési paraméterek testreszabásához.
Az üzenetsor-eseményindító egy paramétert departmentId
biztosít. Egy üzenetsor { "departmentId" : "Finance" }
a pénzügyi részleg összes rekordját visszaadja.
Attribútumok
A folyamaton belüli és az izolált feldolgozói folyamat C# kódtárai attribútumokkal határozzák meg a függvényt. A C#-szkript ehelyett egy function.json konfigurációs fájlt használ a C#-szkriptelési útmutatóban leírtak szerint.
Attribútumtulajdonság | Leírás |
---|---|
Kapcsolat | Egy alkalmazásbeállítás vagy beállításgyűjtemény neve, amely meghatározza, hogyan csatlakozhat a lekérdezett Azure Cosmos DB-fiókhoz. További információ: Kapcsolatok. |
DatabaseName | Az Azure Cosmos DB-adatbázis neve a figyelt tárolóval. |
ContainerName | A figyelt tároló neve. |
PartitionKey | Megadja a keresés partíciókulcs-értékét. Tartalmazhat kötési paramétereket. A particionált tárolókban lévő keresésekhez szükséges. |
Azonosító | A lekérni kívánt dokumentum azonosítója. Ez a tulajdonság támogatja a kötési kifejezéseket. Ne állítsa be a tulajdonságokat és SqlQuery a Id tulajdonságokat sem. Ha egyiket sem állítja be, a rendszer lekéri a teljes tárolót. |
SqlQuery | Több dokumentum lekéréséhez használt Azure Cosmos DB SQL-lekérdezés. A tulajdonság támogatja a futtatókörnyezet-kötéseket, ahogyan ebben a példában is látható: SELECT * FROM c where c.departmentId = {departmentId} . Ne állítsa be a tulajdonságokat és SqlQuery a Id tulajdonságokat sem. Ha egyiket sem állítja be, a rendszer lekéri a teljes tárolót. |
PreferredLocations | (Nem kötelező) Meghatározza a földrajzilag replikált adatbázisfiókok előnyben részesített helyét (régióit) az Azure Cosmos DB szolgáltatásban. Az értékeket vesszővel kell elválasztani. Például: East US,South Central US,North Europe . |
Dekorátorok
Csak a Python v2 programozási modellre vonatkozik.
A Python v2-függvények a cosmos_db_input
dekorátor használatával vannak definiálva, amely támogatja ezeket a tulajdonságokat a bővítmény verziójától függően:
Tulajdonság | Leírás |
---|---|
arg_name |
A függvénykódban használt változónév, amely a módosításokat tartalmazó dokumentumok listáját jelöli. |
database_name |
Az Azure Cosmos DB-adatbázis neve a figyelt gyűjteménysel. |
container_name |
A figyelt Azure Cosmos DB-gyűjtemény neve. |
connection |
A figyelt Azure Cosmos DB kapcsolati sztring. |
partition_key |
A figyelt Azure Cosmos DB partíciókulcsa. |
id |
A lekérni kívánt dokumentum azonosítója. |
A function.json használatával definiált Python-függvények esetében lásd a Konfiguráció szakaszt.
Jegyzetek
A Java-függvények futtatókörnyezeti kódtárában használja a jegyzetet az @CosmosDBInput
Azure Cosmos DB-ből beolvasott paramétereken. A széljegyzet a következő tulajdonságokat támogatja:
Konfiguráció
Csak a Python v1 programozási modellre vonatkozik.
Az alábbi táblázat a function.json fájlban beállított kötéskonfigurációs tulajdonságokat ismerteti, ahol a tulajdonságok bővítményverziónként eltérnek:
function.json tulajdonság | Leírás |
---|---|
type | A beállításnak a cosmosDB következőnek kell lennie: . |
direction | A beállításnak a in következőnek kell lennie: . |
név | A függvénykódban használt változónév, amely a módosításokat tartalmazó dokumentumok listáját jelöli. |
kapcsolat | Egy alkalmazásbeállítás vagy beállítástároló neve, amely meghatározza, hogyan csatlakozhat a figyelt Azure Cosmos DB-fiókhoz. További információ: Kapcsolatok. |
databaseName | Az Azure Cosmos DB-adatbázis neve a figyelt tárolóval. |
containerName | A figyelt tároló neve. |
partitionKey | Megadja a keresés partíciókulcs-értékét. Tartalmazhat kötési paramétereket. A particionált tárolókban lévő keresésekhez szükséges. |
id | A lekérni kívánt dokumentum azonosítója. Ez a tulajdonság támogatja a kötési kifejezéseket. Ne állítsa be a tulajdonságokat és sqlQuery a id tulajdonságokat sem. Ha egyiket sem állítja be, a rendszer lekéri a teljes tárolót. |
sqlQuery | Több dokumentum lekéréséhez használt Azure Cosmos DB SQL-lekérdezés. A tulajdonság támogatja a futtatókörnyezet-kötéseket, ahogyan ebben a példában is látható: SELECT * FROM c where c.departmentId = {departmentId} . Ne állítsa be a tulajdonságokat és sqlQuery a id tulajdonságokat sem. Ha egyiket sem állítja be, a rendszer lekéri a teljes tárolót. |
preferredLocations | (Nem kötelező) Meghatározza a földrajzilag replikált adatbázisfiókok előnyben részesített helyét (régióit) az Azure Cosmos DB szolgáltatásban. Az értékeket vesszővel kell elválasztani. Például: East US,South Central US,North Europe . |
A teljes példákért tekintse meg a Példa szakaszt .
Használat
Ha a függvény sikeresen kilép, a bemeneti dokumentum módosításai automatikusan megmaradnak.
A Cosmos DB bemeneti kötés által támogatott paramétertípus a Functions futtatókörnyezet verziójától, a bővítménycsomag verziójától és a használt C# módtól függ.
Ha azt szeretné, hogy a függvény egyetlen dokumentumot dolgoz fel, a Cosmos DB bemeneti kötése a következő típusokhoz kapcsolódhat:
Típus | Leírás |
---|---|
JSON szerializálható típusok | A Functions megpróbálja deszerializálni a dokumentum JSON-adatait egy egyszerű régi CLR-objektum (POCO) típusba. |
Ha azt szeretné, hogy a függvény több dokumentumot dolgoz fel egy lekérdezésből, a Cosmos DB bemeneti kötése a következő típusokhoz kapcsolódhat:
Típus | Leírás |
---|---|
IEnumerable<T> ahol T egy JSON szerializálható típus |
A lekérdezés által visszaadott entitások számbavétele. Minden bejegyzés egy dokumentumot jelöl. |
CosmosClient1 | A Cosmos DB-fiókhoz csatlakoztatott ügyfél. |
1. adatbázis | A Cosmos DB-adatbázishoz csatlakoztatott ügyfél. |
1. tároló | A Cosmos DB-tárolóhoz csatlakoztatott ügyfél. |
1 Ezeknek a típusoknak a használatához hivatkoznia kell a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0-s vagy újabb verziójára, valamint az SDK-típuskötések gyakori függőségeire.
A Java-függvények futtatókörnyezeti kódtárában a @CosmosDBInput jegyzet az Azure Cosmos DB-adatokat teszi elérhetővé a függvény számára. Ez a széljegyzet natív Java-típusokkal, POJ-kkal vagy null értékű értékekkel használható a használatával Optional<T>
.
A dokumentumok frissítése nem történik meg automatikusan a függvény kilépésekor. A függvény dokumentumainak frissítéséhez használjon kimeneti kötést. További részletekért tekintse meg a PowerShell-példát .
A függvény egy paraméteren keresztül DocumentList
teszi elérhetővé az adatokat. A dokumentum módosításai nem lesznek automatikusan megőrizve.
Kapcsolatok
A connectionStringSetting
/connection
tulajdonságok a leaseConnectionStringSetting
/leaseConnection
környezetkonfigurációra mutató hivatkozások, amelyek meghatározzák, hogyan kell az alkalmazásnak csatlakoznia az Azure Cosmos DB-hez. A következőt határozhatják meg:
- Egy kapcsolati sztring tartalmazó alkalmazásbeállítás neve
- Egy megosztott előtag neve több alkalmazásbeállításhoz, valamint identitásalapú kapcsolat definiálása. Ez a beállítás csak a
connection
leaseConnection
bővítmény 4.x vagy újabb verziójához érhető el.
Ha a konfigurált érték egy adott beállítás pontos egyezése, a többi beállítás előtagja pedig egyezik, akkor a rendszer a pontos egyezést használja.
Kapcsolati sztring
Az adatbázisfiók kapcsolati sztring egy olyan alkalmazásbeállításban kell tárolni, amely a kötéskonfiguráció kapcsolattulajdonsága által megadott értéknek megfelelő névvel rendelkezik.
Identitásalapú kapcsolatok
Ha a bővítmény 4.x vagy újabb verzióját használja, ahelyett, hogy titkos kapcsolati sztring használ, az alkalmazás Microsoft Entra-identitást használhat. Ehhez egy közös előtagban definiálhat beállításokat, amelyek leképezik az eseményindító és a kötés konfigurációjának kapcsolat tulajdonságát.
Ebben a módban a bővítményhez a következő tulajdonságok szükségesek:
Tulajdonság | Környezeti változó sablonja | Leírás | Példaérték |
---|---|---|---|
Fiókvégpont | <CONNECTION_NAME_PREFIX>__accountEndpoint |
Az Azure Cosmos DB-fiók végpontjának URI-ja. | <https:// database_account_name.documents.azure.com:443/> |
További tulajdonságok is beállíthatók a kapcsolat testreszabásához. Tekintse meg az identitásalapú kapcsolatok gyakori tulajdonságait.
Az Azure Functions szolgáltatásban üzemeltetett identitásalapú kapcsolatok felügyelt identitást használnak. A rendszer alapértelmezés szerint a rendszer által hozzárendelt identitást használja, bár a felhasználó által hozzárendelt identitás megadható a credential
tulajdonságokkal együtt clientID
. Vegye figyelembe, hogy a felhasználó által hozzárendelt identitás erőforrás-azonosítóval való konfigurálása nem támogatott. Ha más környezetekben, például helyi fejlesztésben fut, a rendszer ehelyett a fejlesztői identitást használja, bár ez testre szabható. Lásd: Helyi fejlesztés identitásalapú kapcsolatokkal.
Engedély megadása az identitáshoz
Bármilyen identitást is használ, rendelkeznie kell a kívánt műveletek végrehajtásához szükséges engedélyekkel. A legtöbb Azure-szolgáltatás esetében ez azt jelenti, hogy egy szerepkört kell hozzárendelnie az Azure RBAC-ben beépített vagy egyéni szerepkörökkel, amelyek biztosítják ezeket az engedélyeket.
Fontos
A célszolgáltatás bizonyos engedélyeket közzétehet, amelyek nem minden környezethez szükségesek. Ahol lehetséges, tartsa be a minimális jogosultság elvét, és csak az identitáshoz szükséges jogosultságokat adja meg. Ha például az alkalmazásnak csak adatforrásból kell olvasnia, használjon olyan szerepkört, amely csak olvasási engedéllyel rendelkezik. Nem lenne helyénvaló olyan szerepkört hozzárendelni, amely lehetővé teszi az írást is a szolgáltatáshoz, mivel ez túlzott engedély lenne egy olvasási művelethez. Hasonlóképpen meg szeretné győződni arról, hogy a szerepkör-hozzárendelés csak az elolvasandó erőforrásokra terjed ki.
A Cosmos DB nem használja az Azure RBAC-t adatműveletekhez. Ehelyett egy Cosmos DB beépített RBAC-rendszert használ, amely hasonló fogalmakra épül. Létre kell hoznia egy szerepkör-hozzárendelést, amely futásidőben hozzáférést biztosít az adatbázisfiókhoz. Az Azure RBAC Management-szerepkörök, például a Tulajdonos nem elegendőek. Az alábbi táblázat azOkat a beépített szerepköröket mutatja be, amelyek az Azure Cosmos DB-bővítmény normál működésben való használatakor ajánlottak. Előfordulhat, hogy az alkalmazás további engedélyeket igényel az Ön által írt kód alapján.
Kötés típusa | Példa beépített szerepkörök1 |
---|---|
Trigger2 | A Cosmos DB beépített adatszolgáltatója |
Bemeneti kötés | Cosmos DB beépített adatolvasó |
Kimeneti kötés | A Cosmos DB beépített adatszolgáltatója |
1 Ezek a szerepkörök nem használhatók Azure RBAC-szerepkör-hozzárendelésben. A szerepkörök hozzárendelésével kapcsolatos részletekért tekintse meg a Cosmos DB beépített RBAC-rendszerdokumentációját .
2 Identitás használatakor a Cosmos DB felügyeleti műveletként kezeli a tároló létrehozását. Nem érhető el adatsík-műveletként az eseményindítóhoz. A függvény beállítása előtt meg kell győződnie arról, hogy az eseményindítóhoz szükséges tárolókat hozza létre (beleértve a bérlettárolót is).