Wyzwalacz usługi Azure Cosmos DB dla usługi Azure Functions w wersji 2.x lub nowszej

Wyzwalacz usługi Azure Cosmos DB używa zestawienia zmian usługi Azure Cosmos DB do nasłuchiwania wstawiania i aktualizacji między partycjami. Kanał informacyjny zmian publikuje nowe i zaktualizowane elementy, a nie w tym aktualizacje z usuwania.

Aby uzyskać informacje na temat konfiguracji i konfiguracji, zobacz omówienie.

Decyzje dotyczące skalowania usługi Cosmos DB dla planów Zużycie i Premium są wykonywane za pośrednictwem skalowania na podstawie celu. Aby uzyskać więcej informacji, zobacz Skalowanie na podstawie celu.

Ważne

W tym artykule są używane karty do obsługi wielu wersji modelu programowania Node.js. Model w wersji 4 jest ogólnie dostępny i ma bardziej elastyczne i intuicyjne środowisko dla deweloperów języka JavaScript i Języka TypeScript. Aby uzyskać więcej informacji na temat sposobu działania modelu w wersji 4, zapoznaj się z przewodnikiem dewelopera dotyczącym usługi Azure Functions Node.js. Aby dowiedzieć się więcej o różnicach między wersjami 3 i v4, zapoznaj się z przewodnikiem migracji.

Usługa Azure Functions obsługuje dwa modele programowania dla języka Python. Sposób definiowania powiązań zależy od wybranego modelu programowania.

Model programowania w języku Python w wersji 2 umożliwia definiowanie powiązań przy użyciu dekoratorów bezpośrednio w kodzie funkcji języka Python. Aby uzyskać więcej informacji, zobacz przewodnik dla deweloperów języka Python.

Ten artykuł obsługuje oba modele programowania.

Przykład

Użycie wyzwalacza zależy od wersji pakietu rozszerzenia i modalności języka C# używanej w aplikacji funkcji, co może być jednym z następujących elementów:

Izolowana biblioteka klas procesów roboczych skompilowana funkcja języka C# jest uruchamiana w procesie odizolowanym od środowiska uruchomieniowego.

Poniższe przykłady zależą od wersji rozszerzenia dla danego trybu języka C#.

W tym przykładzie odwołuje się do prostego ToDoItem typu:

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

Następująca funkcja jest wywoływana w przypadku wstawiania lub aktualizacji w określonej bazie danych i kolekcji.

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "ToDoItems",
    containerName:"TriggerItems",
    Connection = "CosmosDBConnection",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> todoItems,
    FunctionContext context)
{
    if (todoItems is not null && todoItems.Any())
    {
        foreach (var doc in todoItems)
        {
            _logger.LogInformation("ToDoItem: {desc}", doc.Description);
        }
    }
}

Ta funkcja jest wywoływana w przypadku wstawiania lub aktualizacji w określonej bazie danych i kontenerze.

Ze względu na zmiany schematu w zestawie SDK usługi Azure Cosmos DB wersja 4.x rozszerzenia usługi Azure Cosmos DB wymaga biblioteki azure-functions-java-library w wersji 3.0.0 dla funkcji Języka Java.

    @FunctionName("CosmosDBTriggerFunction")
    public void run(
        @CosmosDBTrigger(
            name = "items",
            databaseName = "ToDoList",
            containerName = "Items",
            leaseContainerName="leases",
            connection = "AzureCosmosDBConnection",
            createLeaseContainerIfNotExists = true
        )
        Object inputItem,
        final ExecutionContext context
    ) {
        context.getLogger().info("Items modified: " + inputItems.size());
    }

W bibliotece środowiska uruchomieniowego funkcji Języka Java użyj @CosmosDBTrigger adnotacji dotyczącej parametrów, których wartość pochodzi z usługi Azure Cosmos DB. Tej adnotacji można używać z natywnymi typami Języka Java, obiektami POJO lub wartościami dopuszczanymi wartościami null przy użyciu polecenia Optional<T>.

W poniższym przykładzie przedstawiono funkcję TypeScript wyzwalacza usługi Azure Cosmos DB. Funkcja zapisuje komunikaty dziennika podczas dodawania lub modyfikowania rekordów usługi Azure Cosmos DB.

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

export async function cosmosDBTrigger1(documents: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Cosmos DB function processed ${documents.length} documents`);
}

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: cosmosDBTrigger1,
});

W poniższym przykładzie przedstawiono funkcję JavaScript wyzwalacza usługi Azure Cosmos DB. Funkcja zapisuje komunikaty dziennika podczas dodawania lub modyfikowania rekordów usługi Azure Cosmos DB.

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

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: (documents, context) => {
        context.log(`Cosmos DB function processed ${documents.length} documents`);
    },
});

W poniższym przykładzie pokazano, jak uruchomić funkcję w miarę zmian danych w usłudze Azure Cosmos DB.

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Pamiętaj, że niektóre nazwy atrybutów powiązania zmieniły się w wersji 4.x rozszerzenia usługi Azure Cosmos DB.

W pliku run.ps1 masz dostęp do dokumentu, który wyzwala funkcję za pośrednictwem parametru $Documents .

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)" 

W poniższym przykładzie przedstawiono powiązanie wyzwalacza usługi Azure Cosmos DB. Przykład zależy od tego, czy używasz modelu programowania w wersji 1, czy w wersji 2 języka Python.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(name="documents", 
                       connection="CONNECTION_SETTING",
                       database_name="DB_NAME", 
                       container_name="CONTAINER_NAME", 
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def test_function(documents: func.DocumentList) -> str:
    if documents:
        logging.info('Document id: %s', documents[0]['id'])

Atrybuty

Zarówno w procesie, jak i w izolowanym procesie biblioteki języka C# używają atrybutu CosmosDBTriggerAttribute do zdefiniowania funkcji. Zamiast tego skrypt języka C# używa pliku konfiguracji function.json zgodnie z opisem w przewodniku obsługi skryptów języka C#.

Właściwość atrybutu opis
Połączenie Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
Databasename Nazwa bazy danych usługi Azure Cosmos DB z monitorowanym kontenerem.
ContainerName Nazwa monitorowanego kontenera.
Dzierżawa Połączenie ion (Opcjonalnie) Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z kontem usługi Azure Cosmos DB, które przechowuje kontener dzierżawy.

Jeśli nie zostanie ustawiona, zostanie użyta Connection wartość. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania w portalu. Parametry połączenia kontenera dzierżaw musi mieć uprawnienia do zapisu.
LeaseDatabaseName (Opcjonalnie) Nazwa bazy danych, która przechowuje kontener używany do przechowywania dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta wartość databaseName ustawienia.
LeaseContainerName (Opcjonalnie) Nazwa kontenera używanego do przechowywania dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta wartość leases .
CreateLeaseContainerIfNotExists (Opcjonalnie) Po ustawieniu truewartości parametru kontener dzierżaw jest tworzony automatycznie, gdy jeszcze nie istnieje. Domyślna wartość to false. W przypadku korzystania z tożsamości entra firmy Microsoft, jeśli ustawisz wartość truena , tworzenie kontenerów nie jest dozwoloną operacją , a funkcja nie będzie mogła uruchomić.
LeasesContainerThroughput (Opcjonalnie) Definiuje liczbę jednostek żądań do przypisania podczas tworzenia kontenera dzierżaw. To ustawienie jest używane tylko wtedy, gdy CreateLeaseContainerIfNotExists jest ustawione na true. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania przy użyciu portalu.
LeaseContainerPrefix (Opcjonalnie) Po ustawieniu wartość jest dodawana jako prefiks do dzierżaw utworzonych w kontenerze Dzierżawa dla tej funkcji. Użycie prefiksu umożliwia dwóm oddzielnym usłudze Azure Functions współużytkowania tego samego kontenera dzierżawy przy użyciu różnych prefiksów.
FeedPollDelay (Opcjonalnie) Czas (w milisekundach) dla opóźnienia między sondowaniem partycji pod kątem nowych zmian w kanale informacyjnym, po opróżnieniu wszystkich bieżących zmian. Wartość domyślna to 5000 milisekund lub 5 sekund.
LeaseAcquireInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał uruchamiania zadania obliczeniowego, jeśli partycje są równomiernie dystrybuowane między znane wystąpienia hosta. Wartość domyślna to 13000 (13 sekund).
LeaseExpirationInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał, dla którego dzierżawa jest wykonywana w dzierżawie reprezentującej partycję. Jeśli dzierżawa nie zostanie odnowiona w tym interwale, spowoduje to wygaśnięcie, a własność partycji zostanie przeniesiona do innego wystąpienia. Wartość domyślna to 60000 (60 sekund).
LeaseRenewInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał odnawiania dla wszystkich dzierżaw dla partycji, które są obecnie przechowywane przez wystąpienie. Wartość domyślna to 17000 (17 sekund).
MaxItemsPerInvocation (Opcjonalnie) Po ustawieniu ta właściwość ustawia maksymalną liczbę odebranych elementów na wywołanie funkcji. Jeśli operacje w monitorowanym kontenerze są wykonywane za pomocą procedur składowanych, zakres transakcji jest zachowywany podczas odczytywania elementów ze źródła zmian. W związku z tym liczba odebranych elementów może być większa niż określona wartość, aby elementy zmienione przez tę samą transakcję zostały zwrócone w ramach jednej partii niepodzielnej.
StartFromBeginning (Opcjonalnie) Ta opcja nakazuje wyzwalaczowi odczytywanie zmian od początku historii zmian kontenera zamiast rozpoczynania się od bieżącej godziny. Odczyt od początku działa tylko przy pierwszym uruchomieniu wyzwalacza, tak jak w kolejnych uruchomieniach, punkty kontrolne są już przechowywane. Ustawienie tej opcji na true wartość , gdy istnieją już utworzone dzierżawy, nie ma wpływu.
StartFromTime (Opcjonalnie) Pobiera lub ustawia datę i godzinę, z której ma być inicjowana operacja odczytu zestawienia zmian. Zalecanym formatem jest ISO 8601 z projektantem UTC, takim jak 2021-02-16T14:19:29Z. Służy to tylko do ustawiania stanu początkowego wyzwalacza. Gdy wyzwalacz ma stan dzierżawy, zmiana tej wartości nie ma wpływu.
PreferredLocations (Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład "Wschodnie stany USA,Południowo-środkowe stany USA,Europa Północna".

Dekoratory

Dotyczy tylko modelu programowania w wersji 2 języka Python.

W przypadku funkcji języka Python w wersji 2 zdefiniowanych przy użyciu dekoratora następujące właściwości w pliku cosmos_db_trigger:

Właściwości opis
arg_name Nazwa zmiennej używana w kodzie funkcji, która reprezentuje listę dokumentów ze zmianami.
database_name Nazwa bazy danych usługi Azure Cosmos DB z monitorowaną kolekcją.
collection_name Nazwa monitorowanej kolekcji usługi Azure Cosmos DB.
connection Parametry połączenia monitorowanej usługi Azure Cosmos DB.

Aby zapoznać się z funkcjami języka Python zdefiniowanymi przy użyciu function.json, zobacz sekcję Konfiguracja .

Adnotacje

Ze względu na zmiany schematu w zestawie SDK usługi Azure Cosmos DB wersja 4.x rozszerzenia usługi Azure Cosmos DB wymaga biblioteki azure-functions-java-library w wersji 3.0.0 dla funkcji Języka Java.

Użyj adnotacji @CosmosDBTrigger dotyczącej parametrów odczytujących dane z usługi Azure Cosmos DB. Adnotacja obsługuje następujące właściwości:

Właściwość atrybutu opis
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
name Nazwa funkcji.
Databasename Nazwa bazy danych usługi Azure Cosmos DB z monitorowanym kontenerem.
containerName Nazwa monitorowanego kontenera.
lease Połączenie ionStringSetting (Opcjonalnie) Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z kontem usługi Azure Cosmos DB, które przechowuje kontener dzierżawy.

Jeśli nie zostanie ustawiona, zostanie użyta Connection wartość. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania w portalu. Parametry połączenia kontenera dzierżaw musi mieć uprawnienia do zapisu.
leaseDatabaseName (Opcjonalnie) Nazwa bazy danych, która przechowuje kontener używany do przechowywania dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta wartość databaseName ustawienia.
leaseContainerName (Opcjonalnie) Nazwa kontenera używanego do przechowywania dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta wartość leases .
createLeaseContainerIfNotExists (Opcjonalnie) Po ustawieniu truewartości parametru kontener dzierżaw jest tworzony automatycznie, gdy jeszcze nie istnieje. Domyślna wartość to false. W przypadku korzystania z tożsamości entra firmy Microsoft, jeśli ustawisz wartość na true, tworzenie kontenerów nie jest dozwoloną operacją , a funkcja nie zostanie uruchomiona.
leasesContainerThroughput (Opcjonalnie) Definiuje liczbę jednostek żądań do przypisania podczas tworzenia kontenera dzierżaw. To ustawienie jest używane tylko wtedy, gdy CreateLeaseContainerIfNotExists jest ustawione na true. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania przy użyciu portalu.
leaseContainerPrefix (Opcjonalnie) Po ustawieniu wartość jest dodawana jako prefiks do dzierżaw utworzonych w kontenerze Dzierżawa dla tej funkcji. Użycie prefiksu umożliwia dwóm oddzielnym usłudze Azure Functions współużytkowania tego samego kontenera dzierżawy przy użyciu różnych prefiksów.
feedPollDelay (Opcjonalnie) Czas (w milisekundach) dla opóźnienia między sondowaniem partycji pod kątem nowych zmian w kanale informacyjnym, po opróżnieniu wszystkich bieżących zmian. Wartość domyślna to 5000 milisekund lub 5 sekund.
leaseAcquireInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał uruchamiania zadania obliczeniowego, jeśli partycje są równomiernie dystrybuowane między znane wystąpienia hosta. Wartość domyślna to 13000 (13 sekund).
leaseExpirationInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał, dla którego dzierżawa jest wykonywana w dzierżawie reprezentującej partycję. Jeśli dzierżawa nie zostanie odnowiona w tym interwale, wygaśnie, a własność partycji zostanie przeniesiona do innego wystąpienia. Wartość domyślna to 60000 (60 sekund).
leaseRenewInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał odnawiania dla wszystkich dzierżaw dla partycji, które są obecnie przechowywane przez wystąpienie. Wartość domyślna to 17000 (17 sekund).
maxItemsPerInvocation (Opcjonalnie) Po ustawieniu ta właściwość ustawia maksymalną liczbę odebranych elementów na wywołanie funkcji. Jeśli operacje w monitorowanym kontenerze są wykonywane za pomocą procedur składowanych, zakres transakcji jest zachowywany podczas odczytywania elementów ze źródła zmian. W związku z tym liczba odebranych elementów może być większa niż określona wartość, aby elementy zmienione przez tę samą transakcję zostały zwrócone w ramach jednej partii niepodzielnej.
startFromBeginning (Opcjonalnie) Ta opcja nakazuje wyzwalaczowi odczytywanie zmian od początku historii zmian kontenera zamiast rozpoczynania się od bieżącej godziny. Odczyt od początku działa tylko przy pierwszym uruchomieniu wyzwalacza, tak jak w kolejnych uruchomieniach, punkty kontrolne są już przechowywane. Ustawienie tej opcji na true wartość , gdy istnieją już utworzone dzierżawy, nie ma wpływu.
preferredLocations (Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład "Wschodnie stany USA,Południowo-środkowe stany USA,Europa Północna".

Konfigurowanie

Dotyczy tylko modelu programowania języka Python w wersji 1.

W poniższej tabeli opisano właściwości, które można ustawić dla options obiektu przekazanego app.cosmosDB() do metody . Właściwości type, directioni name nie mają zastosowania do modelu w wersji 4.

W poniższej tabeli opisano właściwości konfiguracji powiązania ustawione w pliku function.json , gdzie właściwości różnią się wersją rozszerzenia:

właściwość function.json opis
type Musi być ustawiona wartość cosmosDBTrigger.
direction Musi być ustawiona wartość in. Ten parametr jest ustawiany automatycznie podczas tworzenia wyzwalacza w witrynie Azure Portal.
name Nazwa zmiennej używana w kodzie funkcji, która reprezentuje listę dokumentów ze zmianami.
Połączenia Nazwa ustawienia aplikacji lub kolekcji ustawień, która określa sposób nawiązywania połączenia z monitorowanym kontem usługi Azure Cosmos DB. Aby uzyskać więcej informacji, zobacz Połączenie ions.
Databasename Nazwa bazy danych usługi Azure Cosmos DB z monitorowanym kontenerem.
containerName Nazwa monitorowanego kontenera.
dzierżawa Połączenie ion (Opcjonalnie) Nazwa ustawienia aplikacji lub kontenera ustawień, który określa sposób nawiązywania połączenia z kontem usługi Azure Cosmos DB, które przechowuje kontener dzierżawy.

Jeśli nie zostanie ustawiona, zostanie użyta connection wartość. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania w portalu. Parametry połączenia kontenera dzierżaw musi mieć uprawnienia do zapisu.
leaseDatabaseName (Opcjonalnie) Nazwa bazy danych, która przechowuje kontener używany do przechowywania dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta wartość databaseName ustawienia.
leaseContainerName (Opcjonalnie) Nazwa kontenera używanego do przechowywania dzierżaw. Jeśli nie zostanie ustawiona, zostanie użyta wartość leases .
createLeaseContainerIfNotExists (Opcjonalnie) Po ustawieniu truewartości parametru kontener dzierżaw jest tworzony automatycznie, gdy jeszcze nie istnieje. Domyślna wartość to false. W przypadku korzystania z tożsamości entra firmy Microsoft, jeśli ustawisz wartość truena , tworzenie kontenerów nie jest dozwoloną operacją , a funkcja nie będzie mogła uruchomić.
leasesContainerThroughput (Opcjonalnie) Definiuje liczbę jednostek żądań do przypisania podczas tworzenia kontenera dzierżaw. To ustawienie jest używane tylko wtedy, gdy createLeaseContainerIfNotExists jest ustawione na true. Ten parametr jest ustawiany automatycznie podczas tworzenia powiązania przy użyciu portalu.
leaseContainerPrefix (Opcjonalnie) Po ustawieniu wartość jest dodawana jako prefiks do dzierżaw utworzonych w kontenerze Dzierżawa dla tej funkcji. Użycie prefiksu umożliwia dwóm oddzielnym usłudze Azure Functions współużytkowania tego samego kontenera dzierżawy przy użyciu różnych prefiksów.
feedPollDelay (Opcjonalnie) Czas (w milisekundach) dla opóźnienia między sondowaniem partycji pod kątem nowych zmian w kanale informacyjnym, po opróżnieniu wszystkich bieżących zmian. Wartość domyślna to 5000 milisekund lub 5 sekund.
leaseAcquireInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał uruchamiania zadania obliczeniowego, jeśli partycje są równomiernie dystrybuowane między znane wystąpienia hosta. Wartość domyślna to 13000 (13 sekund).
leaseExpirationInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał, dla którego dzierżawa jest wykonywana w dzierżawie reprezentującej partycję. Jeśli dzierżawa nie zostanie odnowiona w tym interwale, spowoduje to wygaśnięcie, a własność partycji zostanie przeniesiona do innego wystąpienia. Wartość domyślna to 60000 (60 sekund).
leaseRenewInterval (Opcjonalnie) Po ustawieniu definiuje, w milisekundach, interwał odnawiania dla wszystkich dzierżaw dla partycji, które są obecnie przechowywane przez wystąpienie. Wartość domyślna to 17000 (17 sekund).
maxItemsPerInvocation (Opcjonalnie) Po ustawieniu ta właściwość ustawia maksymalną liczbę odebranych elementów na wywołanie funkcji. Jeśli operacje w monitorowanym kontenerze są wykonywane za pomocą procedur składowanych, zakres transakcji jest zachowywany podczas odczytywania elementów ze źródła zmian. W związku z tym liczba odebranych elementów może być większa niż określona wartość, aby elementy zmienione przez tę samą transakcję zostały zwrócone w ramach jednej partii niepodzielnej.
startFromBeginning (Opcjonalnie) Ta opcja nakazuje wyzwalaczowi odczytywanie zmian od początku historii zmian kontenera zamiast rozpoczynania się od bieżącej godziny. Odczyt od początku działa tylko przy pierwszym uruchomieniu wyzwalacza, tak jak w kolejnych uruchomieniach, punkty kontrolne są już przechowywane. Ustawienie tej opcji na true wartość , gdy istnieją już utworzone dzierżawy, nie ma wpływu.
startFromTime (Opcjonalnie) Pobiera lub ustawia datę i godzinę, z której ma być inicjowana operacja odczytu zestawienia zmian. Zalecanym formatem jest ISO 8601 z projektantem UTC, takim jak 2021-02-16T14:19:29Z. Służy to tylko do ustawiania stanu początkowego wyzwalacza. Gdy wyzwalacz ma stan dzierżawy, zmiana tej wartości nie ma wpływu.
preferredLocations (Opcjonalnie) Definiuje preferowane lokalizacje (regiony) dla kont baz danych replikowanych geograficznie w usłudze Azure Cosmos DB. Wartości powinny być rozdzielane przecinkami. Na przykład "Wschodnie stany USA,Południowo-środkowe stany USA,Europa Północna".

Zobacz sekcję Przykład, aby zapoznać się z kompletnymi przykładami.

Sposób użycia

Wyzwalacz wymaga drugiej kolekcji używanej do przechowywania dzierżaw w partycjach. Zarówno monitorowana kolekcja, jak i kolekcja zawierająca dzierżawy muszą być dostępne, aby wyzwalacz działał.

Ważne

Jeśli wiele funkcji jest skonfigurowanych do używania wyzwalacza usługi Azure Cosmos DB dla tej samej kolekcji, każda z funkcji powinna używać dedykowanej kolekcji dzierżaw lub określać inną LeaseCollectionPrefix dla każdej funkcji. W przeciwnym razie wyzwalana jest tylko jedna z funkcji. Aby uzyskać informacje o prefiksie, zobacz sekcję Atrybuty.

Ważne

Jeśli wiele funkcji jest skonfigurowanych do używania wyzwalacza usługi Azure Cosmos DB dla tej samej kolekcji, każda z funkcji powinna używać dedykowanej kolekcji dzierżaw lub określać inną leaseCollectionPrefix dla każdej funkcji. W przeciwnym razie wyzwalana jest tylko jedna z funkcji. Aby uzyskać informacje o prefiksie, zobacz sekcję Adnotacje.

Ważne

Jeśli wiele funkcji jest skonfigurowanych do używania wyzwalacza usługi Azure Cosmos DB dla tej samej kolekcji, każda z funkcji powinna używać dedykowanej kolekcji dzierżaw lub określać inną leaseCollectionPrefix dla każdej funkcji. W przeciwnym razie zostanie wyzwolona tylko jedna z funkcji. Aby uzyskać informacje o prefiksie, zobacz sekcję Konfiguracja.

Wyzwalacz nie wskazuje, czy dokument został zaktualizowany, czy wstawiony, tylko udostępnia sam dokument. Jeśli musisz obsługiwać aktualizacje i wstawiać inaczej, możesz to zrobić, implementując pola znacznika czasu na potrzeby wstawiania lub aktualizacji.

Typ parametru obsługiwany przez wyzwalacz usługi Azure Cosmos DB zależy od wersji środowiska uruchomieniowego usługi Functions, wersji pakietu rozszerzenia i używanej modalności języka C#.

Jeśli chcesz, aby funkcja przetwarzała pojedynczy dokument, wyzwalacz usługi Cosmos DB może powiązać z następującymi typami:

Type Opis
Typy serializowalne w formacie JSON Usługa Functions próbuje wykonać deserializacji danych JSON dokumentu z zestawienia zmian usługi Cosmos DB na zwykły typ obiektu CLR (POCO).

Jeśli chcesz, aby funkcja przetwarzała partię dokumentów, wyzwalacz usługi Cosmos DB może powiązać z następującymi typami:

Type Opis
IEnumerable<T>gdzie T jest typem serializowalnym JSON Wyliczenie jednostek uwzględnionych w partii. Każdy wpis reprezentuje jeden dokument ze źródła zmian usługi Cosmos DB.

Połączenia

Właściwości connectionStringSetting/connection i leaseConnectionStringSetting/leaseConnection są odwołaniami do konfiguracji środowiska, która określa sposób łączenia aplikacji z usługą Azure Cosmos DB. Mogą one określać:

Jeśli skonfigurowana wartość jest dokładnie zgodna z pojedynczym ustawieniem i dopasowaniem prefiksu dla innych ustawień, zostanie użyte dokładne dopasowanie.

Connection string

Parametry połączenia dla konta bazy danych powinny być przechowywane w ustawieniu aplikacji z nazwą zgodną z wartością określoną przez właściwość połączenia konfiguracji powiązania.

Połączenia oparte na tożsamościach

Jeśli używasz rozszerzenia w wersji 4.x lub nowszej, zamiast używać parametry połączenia z wpisem tajnym, możesz użyć tożsamości Microsoft Entra. W tym celu należy zdefiniować ustawienia w ramach wspólnego prefiksu, który mapuje na właściwość connection w konfiguracji wyzwalacza i powiązania.

W tym trybie rozszerzenie wymaga następujących właściwości:

Właściwości Szablon zmiennej środowiskowej opis Przykładowa wartość
Punkt końcowy konta <CONNECTION_NAME_PREFIX>__accountEndpoint Identyfikator URI punktu końcowego konta usługi Azure Cosmos DB. <https:// database_account_name.documents.azure.com:443/>

Aby dostosować połączenie, można ustawić dodatkowe właściwości. Zobacz Typowe właściwości połączeń opartych na tożsamościach.

W przypadku hostowania w usłudze Azure Functions połączenia oparte na tożsamościach używają tożsamości zarządzanej. Tożsamość przypisana przez system jest używana domyślnie, chociaż tożsamości przypisanej przez użytkownika można określić za credential pomocą właściwości i clientID . Należy pamiętać, że konfigurowanie tożsamości przypisanej przez użytkownika przy użyciu identyfikatora zasobu nie jest obsługiwane. W przypadku uruchamiania w innych kontekstach, takich jak programowanie lokalne, tożsamość dewelopera jest używana, chociaż można to dostosować. Zobacz Programowanie lokalne z połączeniami opartymi na tożsamościach.

Udzielanie uprawnień tożsamości

Niezależnie od używanej tożsamości musi mieć uprawnienia do wykonywania zamierzonych akcji. W przypadku większości usług platformy Azure oznacza to, że musisz przypisać rolę w kontroli dostępu opartej na rolach platformy Azure przy użyciu wbudowanych lub niestandardowych ról, które zapewniają te uprawnienia.

Ważne

Niektóre uprawnienia mogą być uwidocznione przez usługę docelową, które nie są niezbędne dla wszystkich kontekstów. Jeśli to możliwe, przestrzegaj zasady najniższych uprawnień, udzielając tożsamości tylko wymaganych uprawnień. Jeśli na przykład aplikacja musi mieć możliwość odczytu tylko ze źródła danych, użyj roli, która ma uprawnienia tylko do odczytu. Niewłaściwe byłoby przypisanie roli, która umożliwia również zapisywanie w tej usłudze, ponieważ byłoby to nadmierne uprawnienie do operacji odczytu. Podobnie należy upewnić się, że przypisanie roli jest ograniczone tylko do zasobów, które należy odczytać.

Usługa Cosmos DB nie używa kontroli dostępu opartej na rolach platformy Azure na potrzeby operacji na danych. Zamiast tego używa wbudowanego systemu RBAC usługi Cosmos DB, który jest oparty na podobnych pojęciach. Należy utworzyć przypisanie roli, które zapewnia dostęp do konta bazy danych w czasie wykonywania. Role zarządzania RBAC platformy Azure, takie jak Właściciel , nie są wystarczające. W poniższej tabeli przedstawiono wbudowane role, które są zalecane podczas korzystania z rozszerzenia usługi Azure Cosmos DB w normalnej operacji. Aplikacja może wymagać dodatkowych uprawnień na podstawie zapisanego kodu.

Typ powiązania Przykładowe wbudowane role1
Wyzwalacz2 Współautor danych wbudowanych w usłudze Cosmos DB
Powiązanie wejściowe Wbudowany czytnik danych usługi Cosmos DB
Powiązanie wyjściowe Współautor danych wbudowanych w usłudze Cosmos DB

1 Tych ról nie można używać w przypisaniu roli RBAC platformy Azure. Aby uzyskać szczegółowe informacje na temat przypisywania tych ról, zobacz wbudowaną dokumentację systemu RBAC usługi Cosmos DB.

2 W przypadku korzystania z tożsamości usługa Cosmos DB traktuje tworzenie kontenera jako operację zarządzania. Nie jest ona dostępna jako operacja płaszczyzny danych dla wyzwalacza. Przed skonfigurowaniem funkcji należy upewnić się, że utworzysz kontenery wymagane przez wyzwalacz (w tym kontener dzierżawy).

Następne kroki