Azure Cosmos DB uitvoerbinding voor Azure Functions 2.x en hoger

Azure Functions ondersteunt twee programmeermodellen voor Python. De manier waarop u uw bindingen definieert, is afhankelijk van het gekozen programmeermodel.

Dit artikel ondersteunt beide programmeermodellen.

U kunt een C#-functie maken met behulp van een van de volgende C#-modi:

• Geïsoleerd werkrolmodel: gecompileerde C#-functie die wordt uitgevoerd in een werkproces dat is geïsoleerd van de runtime. Geïsoleerd werkproces is vereist voor de ondersteuning van C#-functies die worden uitgevoerd op LTS- en niet-LTS-versies .NET en het .NET Framework. Extensies voor geïsoleerde werkprocesfuncties maken gebruik van Microsoft.Azure.Functions.Worker.Extensions.* naamruimten.
• In-process model: gecompileerde C#-functie die wordt uitgevoerd in hetzelfde proces als de Functions-runtime. In een variatie van dit model kunnen functies worden uitgevoerd met behulp van C#-scripting. Dit wordt voornamelijk ondersteund voor het bewerken van de C#-portal. Extensies voor in-process-functies maken gebruik van Microsoft.Azure.WebJobs.Extensions.* naamruimten.

Go-ondersteuning is momenteel niet beschikbaar voor deze binding.

• Wachtrijtrigger, bericht opslaan in database via retourwaarde
• HTTP-trigger, één document opslaan in database via retourwaarde
• HTTP-trigger, één document opslaan in de database via OutputBinding
• HTTP-trigger, meerdere documenten opslaan in database via OutputBinding

Wachtrijtrigger, bericht opslaan in database via retourwaarde

In het volgende voorbeeld ziet u een Java functie waarmee een document wordt toegevoegd aan een database met gegevens uit een bericht in Queue Storage.

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

HTTP-trigger, één document opslaan in database via retourwaarde

In het volgende voorbeeld ziet u een Java functie waarvan de handtekening is geannoteerd met @CosmosDBOutput en de retourwaarde van het type String heeft. Het JSON-document dat door de functie wordt geretourneerd, wordt automatisch naar de bijbehorende Azure Cosmos DB verzameling geschreven.

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

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

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

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

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

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

        return jsonDocument;
    }

HTTP-trigger, één document opslaan in de database via OutputBinding

In het volgende voorbeeld ziet u een Java functie waarmee een document naar Azure Cosmos DB wordt geschreven via een OutputBinding<T> uitvoerparameter. In dit voorbeeld moet de outputItem parameter worden voorzien van aantekeningen, @CosmosDBOutputniet de functiehandtekening. Met behulp van OutputBinding<T> kunt uw functie profiteren van de binding om het document naar Azure Cosmos DB te schrijven, terwijl u ook een andere waarde kunt retourneren aan de functie-aanroeper, zoals een JSON- of XML-document.

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

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

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

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

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

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

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

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

HTTP-trigger, meerdere documenten opslaan in database via OutputBinding

In het volgende voorbeeld ziet u een Java functie waarmee meerdere documenten naar Azure Cosmos DB worden geschreven via een OutputBinding<T> uitvoerparameter. In dit voorbeeld wordt de outputItem parameter geannoteerd met @CosmosDBOutput, niet de functiehandtekening. De uitvoerparameter outputItem heeft een lijst ToDoItem met objecten als sjabloonparametertype. Met behulp van OutputBinding<T> kan uw functie profiteren van de binding om de documenten naar Azure Cosmos DB te schrijven, terwijl u ook een andere waarde kunt retourneren aan de functie-aanroeper, zoals een JSON- of XML-document.

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

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

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

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

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

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

          items.add(item);
        }

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

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

Gebruik in de runtimebibliotheek van Java functions de aantekening @CosmosDBOutput voor parameters die naar Azure Cosmos DB zijn geschreven. Het parametertype aantekening moet worden OutputBinding<T>, waarbij T een systeemeigen Java of een POJO is.

In het volgende voorbeeld ziet u hoe u gegevens naar Azure Cosmos DB schrijft met behulp van een uitvoerbinding. De binding wordt gedeclareerd in het configuratiebestand van de functie (functions.json) en haalt gegevens uit een wachtrijbericht op en schrijft naar een Azure Cosmos DB document.

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

In het bestand run.ps1 wordt het object dat is geretourneerd van de functie toegewezen aan een EmployeeDocument object, dat in de database wordt bewaard.

param($QueueItem, $TriggerMetadata) 

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

In het volgende voorbeeld ziet u hoe u een document naar een Azure Cosmos DB-database schrijft als uitvoer van een functie. Het voorbeeld is afhankelijk van of u het v1 of v2 Python programmeermodel gebruikt.

import logging
import azure.functions as func

app = func.FunctionApp()

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

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

import azure.functions as func

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

    request_body = req.get_body()

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

    return 'OK'

Kenmerken

Zowel in-processals geïsoleerde werkproces C#-bibliotheken gebruiken kenmerken om de functie te definiëren. C#-script maakt in plaats daarvan gebruik van een function.json configuratiebestand, zoals beschreven in de handleiding voor C#-scripts.

Decorateurs

Alleen aan het Python v2-programmeermodel.

Voor Python v2-functies die zijn gedefinieerd met behulp van een decorator, zijn de volgende eigenschappen op de cosmos_db_output:

Zie de sectie Configuration voor Python functies die zijn gedefinieerd met behulp van function.json.

Aantekeningen

Gebruik in de runtimebibliotheek van Java functions de @CosmosDBOutput annotatie voor parameters die naar Azure Cosmos DB schrijven. De aantekening ondersteunt de volgende eigenschappen:

• naam
• connectionStringSetting
• databaseName
• collectionName
• createIfNotExists
• Datatype
• partitionKey
• preferredLocations
• gebruikMeerdereSchrijflocaties

Configuratie

Alleen aan het programmeermodel Python v1.

In de volgende tabel worden de bindingsconfiguratie-eigenschappen uitgelegd die u in het function.json-bestand hebt ingesteld, waarbij de eigenschappen verschillen per extensieversie:

De parameter van de uitvoerfunctie moet worden gedefinieerd als func.Out[func.Document]. Raadpleeg het uitvoervoorbeeld voor meer informatie.

Het parametertype dat wordt ondersteund door de Cosmos DB-uitvoerbinding, is afhankelijk van de runtimeversie van Functions, de versie van het extensiepakket en de gebruikte C#-modaliteit.