Merge pull request #226854 from vmagelo/function-work-cosmos

v-dirichards · web-flow · commit 18684df25ae3 · 2023-02-16T13:29:34.000-06:00
Add Python Pivot to Cosmos article where C# and JavaScript already exist
diff --git a/articles/azure-functions/TOC.yml b/articles/azure-functions/TOC.yml
@@ -166,6 +166,9 @@
         - name: JavaScript
           displayName: Connect to a database, Azure Cosmos DB
           href: functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-javascript
+        - name: Python
+          displayName: Connect to a database, Azure Cosmos DB
+          href: functions-add-output-binding-cosmos-db-vs-code.md?pivots=programming-language-python
 - name: Tutorials
   items:
     - name: Functions with Logic Apps
diff --git a/articles/azure-functions/functions-add-output-binding-cosmos-db-vs-code.md b/articles/azure-functions/functions-add-output-binding-cosmos-db-vs-code.md
@@ -1,10 +1,10 @@
 ---
 title: Connect Azure Functions to Azure Cosmos DB using Visual Studio Code
 description: Learn how to connect Azure Functions to an Azure Cosmos DB account by adding an output binding to your Visual Studio Code project.
-ms.date: 08/17/2021
+ms.date: 02/09/2023
 ms.topic: quickstart
 zone_pivot_groups: programming-languages-set-functions-temp
-ms.devlang: csharp, javascript
+ms.devlang: csharp, javascript, python
 ms.custom: mode-ui, vscode-azure-extension-update-completed, ignite-2022
 ---
 
@@ -20,6 +20,9 @@ Before you begin, you must complete the [quickstart: Create a C# function in Azu
 ::: zone pivot="programming-language-javascript"  
 Before you begin, you must complete the [quickstart: Create a JavaScript function in Azure using Visual Studio Code](create-first-function-vs-code-node.md). If you already cleaned up resources at the end of that article, go through the steps again to recreate the function app and related resources in Azure.  
 ::: zone-end
+::: zone pivot="programming-language-python"  
+Before you begin, you must complete the [quickstart: Create a Python function in Azure using Visual Studio Code](create-first-function-vs-code-python.md). If you already cleaned up resources at the end of that article, go through the steps again to recreate the function app and related resources in Azure.  
+::: zone-end
 
 ## Configure your environment
 
@@ -30,7 +33,7 @@ Before you get started, make sure to install the [Azure Databases extension](htt
 > [!IMPORTANT]
 > [Azure Cosmos DB serverless](../cosmos-db/serverless.md) is now generally available. This consumption-based mode makes Azure Cosmos DB a strong option for serverless workloads. To use Azure Cosmos DB in serverless mode, choose **Serverless** as the **Capacity mode** when creating your account.
 
-1. In Visual Studio Code, select **View** > **Command Pallete...** then in the command pallete search for `Azure Databases: Create Server...`
+1. In Visual Studio Code, select **View** > **Command Palette...** then in the command palette search for `Azure Databases: Create Server...`
 
 1. Provide the following information at the prompts:
 
@@ -46,7 +49,7 @@ Before you get started, make sure to install the [Azure Databases extension](htt
 
 ## Create an Azure Cosmos DB database and container
 
-1. Select the Azure icon in the Activity bar, expand **Resources** > **Azure Cosmos DB**, right-click (Ctrl+click on macOS) your account, and select **Create database...**.
+1. Select the Azure icon in the Activity bar, expand **Resources** > **Azure Cosmos DB**, right-click (Ctrl+select on macOS) your account, and select **Create database...**.
 
 1. Provide the following information at the prompts:
 
@@ -60,9 +63,9 @@ Before you get started, make sure to install the [Azure Databases extension](htt
 
 ## Update your function app settings
 
-In the [previous quickstart article](./create-first-function-vs-code-csharp.md), you created a function app in Azure. In this article, you update your app to write JSON documents to the Azure Cosmos DB container you've just created. To connect to your Azure Cosmos DB account, you must add its connection string to your app settings. You then download the new setting to your local.settings.json file so you can connect to your Azure Cosmos DB account when running locally.
+In the [previous quickstart article](./create-first-function-vs-code-csharp.md), you created a function app in Azure. In this article, you update your app to write JSON documents to the Azure Cosmos DB container you've created. To connect to your Azure Cosmos DB account, you must add its connection string to your app settings. You then download the new setting to your local.settings.json file so you can connect to your Azure Cosmos DB account when running locally.
 
-1. In Visual Studio Code, right-click (Ctrl+click on macOS) on your new Azure Cosmos DB account, and select **Copy Connection String**.
+1. In Visual Studio Code, right-click (Ctrl+select on macOS) on your new Azure Cosmos DB account, and select **Copy Connection String**.
 
     :::image type="content" source="./media/functions-add-output-binding-cosmos-db-vs-code/copy-connection-string.png" alt-text="Copying the Azure Cosmos DB connection string" border="true":::
 
@@ -73,7 +76,7 @@ In the [previous quickstart article](./create-first-function-vs-code-csharp.md),
     |Prompt| Selection|
     |--|--|
     |**Enter new app setting name**| Type `CosmosDbConnectionString`.|
-    |**Enter value for "CosmosDbConnectionString"**| Paste the connection string of your Azure Cosmos DB account you just copied.|
+    |**Enter value for "CosmosDbConnectionString"**| Paste the connection string of your Azure Cosmos DB account you copied.|
 
     This creates an application setting named connection `CosmosDbConnectionString` in your function app in Azure. Now, you can download this setting to your local.settings.json file.
 
@@ -89,7 +92,7 @@ Because you're using an Azure Cosmos DB output binding, you must have the corres
 
 ::: zone pivot="programming-language-csharp"
 
-With the exception of HTTP and timer triggers, bindings are implemented as extension packages. Run the following [dotnet add package](/dotnet/core/tools/dotnet-add-package) command in the Terminal window to add the Azure Cosmos DB extension package to your project.
+Except for HTTP and timer triggers, bindings are implemented as extension packages. Run the following [dotnet add package](/dotnet/core/tools/dotnet-add-package) command in the Terminal window to add the Azure Cosmos DB extension package to your project.
 
 # [In-process](#tab/in-process)
 ```bash
@@ -102,11 +105,11 @@ dotnet add package Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
 ---
 ::: zone-end
 
-::: zone pivot="programming-language-javascript"
+::: zone pivot="programming-language-javascript,programming-language-python"
 
 Your project has been configured to use [extension bundles](functions-bindings-register.md#extension-bundles), which automatically installs a predefined set of extension packages. 
 
-Extension bundles usage is enabled in the host.json file at the root of the project, which appears as follows:
+Extension bundles usage is enabled in the *host.json* file at the root of the project, which appears as follows:
 
 :::code language="json" source="~/functions-quickstart-java/functions-add-output-binding-storage-queue/host.json":::
 
@@ -116,7 +119,7 @@ Now, you can add the Azure Cosmos DB output binding to your project.
 
 ## Add an output binding
 
-In Functions, each type of binding requires a `direction`, `type`, and a unique `name` to be defined in the function.json file. The way you define these attributes depends on the language of your function app.
+In Functions, each type of binding requires a `direction`, `type`, and a unique `name` to be defined in the *function.json* file. The way you define these attributes depends on the language of your function app.
 
 ::: zone pivot="programming-language-csharp"
 
@@ -137,7 +140,7 @@ Open the *HttpExample.cs* project file and add the following classes:
 
 :::code language="csharp" source="~/functions-docs-csharp/functions-add-output-binding-cosmos-db-isolated/HttpExample.cs" range="36-46":::
 
-The `MyDocument` class defines an object that gets written to the database. The connection string for the Storage account is set by the `Connection` property. In this case, you could omit `Connection` because you are already using the default storage account.
+The `MyDocument` class defines an object that gets written to the database. The connection string for the Storage account is set by the `Connection` property. In this case, you could omit `Connection` because you're already using the default storage account.
 
 The `MultiResponse` class allows you to both write to the specified collection in the Azure Cosmos DB and return an HTTP success message. Because you need to return a `MultiResponse` object, you need to also update the method signature.
 
@@ -149,9 +152,9 @@ Specific attributes specify the name of the container and the name of its parent
 
 ::: zone pivot="programming-language-javascript"
 
-Binding attributes are defined directly in the function.json file. Depending on the binding type, additional properties may be required. The [Azure Cosmos DB output configuration](./functions-bindings-cosmosdb-v2-output.md#configuration) describes the fields required for an Azure Cosmos DB output binding. The extension makes it easy to add bindings to the function.json file. 
+Binding attributes are defined directly in the *function.json* file. Depending on the binding type, other properties may be required. The [Azure Cosmos DB output configuration](./functions-bindings-cosmosdb-v2-output.md#configuration) describes the fields required for an Azure Cosmos DB output binding. The extension makes it easy to add bindings to the *function.json* file. 
 
-To create a binding, right-click (Ctrl+click on macOS) the `function.json` file in your HttpTrigger folder and choose **Add binding...**. Follow the prompts to define the following binding properties for the new binding:
+To create a binding, right-click (Ctrl+select on macOS) the *function.json* file in your HttpTrigger folder and choose **Add binding...**. Follow the prompts to define the following binding properties for the new binding:
 
 | Prompt | Value | Description |
 | -------- | ----- | ----------- |
@@ -165,7 +168,7 @@ To create a binding, right-click (Ctrl+click on macOS) the `function.json` file
 | **Partition key (optional)** | *leave blank* | Only required when the output binding creates the container. |
 | **Collection throughput (optional)** | *leave blank* | Only required when the output binding creates the container. |
 
-A binding is added to the `bindings` array in your function.json, which should look like the following after removing any `undefined` values present
+A binding is added to the `bindings` array in your *function.json*, which should look like the following after removing any `undefined` values present
 
 ```json
 {
@@ -181,6 +184,57 @@ A binding is added to the `bindings` array in your function.json, which should l
 
 ::: zone-end
 
+::: zone pivot="programming-language-python"
+
+The way that you define the new binding depends on your Python programming model.
+
+# [v1](#tab/v1)
+
+Binding attributes are defined directly in the *function.json* file. Depending on the binding type, other properties may be required. The [Azure Cosmos DB output configuration](./functions-bindings-cosmosdb-v2-output.md#configuration) describes the fields required for an Azure Cosmos DB output binding. The extension makes it easy to add bindings to the *function.json* file. 
+
+To create a binding, right-select (Ctrl+select on macOS) the *function.json* file in your HttpTrigger folder and choose **Add binding...**. Follow the prompts to define the following binding properties for the new binding:
+
+| Prompt | Value | Description |
+| -------- | ----- | ----------- |
+| **Select binding direction** | `out` | The binding is an output binding. |
+| **Select binding with direction "out"** | `Azure Cosmos DB` | The binding is an Azure Cosmos DB binding. |
+| **The name used to identify this binding in your code** | `outputDocument` | Name that identifies the binding parameter referenced in your code. |
+| **The Azure Cosmos DB database where data will be written** | `my-database` | The name of the Azure Cosmos DB database containing the target container. |
+| **Database collection where data will be written** | `my-container` | The name of the Azure Cosmos DB container where the JSON documents will be written. |
+| **If true, creates the Azure Cosmos DB database and collection** | `false` | The target database and container already exist. |
+| **Select setting from "local.setting.json"** | `CosmosDbConnectionString` | The name of an application setting that contains the connection string for the Azure Cosmos DB account. |
+| **Partition key (optional)** | *leave blank* | Only required when the output binding creates the container. |
+| **Collection throughput (optional)** | *leave blank* | Only required when the output binding creates the container. |
+
+A binding is added to the `bindings` array in your *function.json*, which should look like the following after removing any `undefined` values present
+
+```json
+{
+    "type": "cosmosDB",
+    "direction": "out",
+    "name": "outputDocument",
+    "databaseName": "my-database",
+    "collectionName": "my-container",
+    "createIfNotExists": "false",
+    "connectionStringSetting": "CosmosDbConnectionString"
+}
+```
+
+# [v2](#tab/v2)
+
+Binding attributes are defined directly in the *function_app.py* file. You use the `cosmos_db_output` decorator to add an [Azure Cosmos DB output binding](/azure/azure-functions/functions-bindings-triggers-python#azure-cosmos-db-output-binding):
+
+```python
+@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", 
+    collection_name="my-container", connection_string_setting="CosmosDbConnectionString")
+```
+
+In this code, `arg_name` identifies the binding parameter referenced in your code, `database_name` and `collection_name` are the database and collection names that the binding writes to, and `connection_string_setting` is the name of an application setting that contains the connection string for the Storage account, which is in the CosmosDbConnectionString setting in the *local.settings.json* file.
+
+---
+
+::: zone-end
+
 ## Add code that uses the output binding
 
 ::: zone pivot="programming-language-csharp"  
@@ -295,11 +349,90 @@ This code now returns a `MultiResponse` object that contains both a document and
 
 ::: zone-end  
 
+::: zone pivot="programming-language-python"
+
+# [v1](#tab/v1)
+
+Update *HttpExample\\\_\_init\_\_.py* to match the following code. Add the `outputDocument` parameter to the function definition and `outputDocument.set()` under the `if name:` statement:
+
+```python
+import azure.functions as func
+import logging
+
+def main(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
+    outputDocument: func.Out[func.Document]) -> str:
+
+    name = req.params.get('name')
+    if not name:
+        try:
+            req_body = req.get_json()
+        except ValueError:
+            pass
+        else:
+            name = req_body.get('name')
+
+    if name:
+        outputDocument.set(func.Document.from_dict({"id": name}))
+        msg.set(name)
+        return func.HttpResponse(f"Hello {name}!")
+    else:
+        return func.HttpResponse(
+            "Please pass a name on the query string or in the request body",
+            status_code=400
+        )
+```
+
+The document `{"id": "name"}` is created in the database collection specified in the binding.
+
+# [v2](#tab/v2)
+
+Update *HttpExample\\function_app.py* to match the following code. Add the `outputDocument` parameter to the function definition and `outputDocument.set()` under the `if name:` statement:
+
+```python
+import azure.functions as func
+import logging
+
+app = func.FunctionApp()
+
+@app.function_name(name="HttpTrigger1")
+@app.route(route="hello", auth_level=func.AuthLevel.ANONYMOUS)
+@app.queue_output(arg_name="msg", queue_name="outqueue", connection="AzureWebJobsStorage")
+@app.cosmos_db_output(arg_name="outputDocument", database_name="my-database", collection_name="my-container" connection_string_setting="CosmosDbConnectionString")
+def test_function(req: func.HttpRequest, msg: func.Out[func.QueueMessage],
+    outputDocument: func.Out[func.Document]) -> func.HttpResponse:
+     logging.info('Python HTTP trigger function processed a request.')
+     logging.info('Python Cosmos DB trigger function processed a request.')
+     name = req.params.get('name')
+     if not name:
+        try:
+            req_body = req.get_json()
+        except ValueError:
+            pass
+        else:
+            name = req_body.get('name')
+
+     if name:
+        outputDocument.set(func.Document.from_dict({"id": name}))
+        msg.set(name)
+        return func.HttpResponse(f"Hello {name}!")
+     else:
+        return func.HttpResponse(
+                    "Please pass a name on the query string or in the request body",
+                    status_code=400
+                )
+```
+
+The document `{"id": "name"}` is created in the database collection specified in the binding.
+
+---
+
+::: zone-end
+
 ::: zone pivot="programming-language-csharp"
 [!INCLUDE [functions-run-function-test-local-vs-code-csharp](../../includes/functions-run-function-test-local-vs-code-csharp.md)]
 ::: zone-end
 
-::: zone pivot="programming-language-javascript"
+::: zone pivot="programming-language-javascript,programming-language-python"
 ## Run the function locally
 
 1. As in the previous article, press <kbd>F5</kbd> to start the function app project and Core Tools. 
@@ -358,3 +491,8 @@ You've updated your HTTP triggered function to write JSON documents to an Azure
 
 + [Azure Functions JavaScript developer guide](functions-reference-node.md)  
 ::: zone-end  
+::: zone pivot="programming-language-python"
++ [Examples of complete Function projects in Python](/samples/browse/?products=azure-functions&languages=python).
+
++ [Azure Functions Python developer guide](functions-reference-node.md)  
+::: zone-end  
diff --git a/articles/zone-pivot-groups.yml b/articles/zone-pivot-groups.yml
@@ -335,6 +335,8 @@ groups:
     title: C#
   - id: programming-language-javascript
     title: JavaScript
+  - id: programming-language-python
+    title: Python
 - id: programming-languages-set-functions-full
   title: Programming languages
   prompt: Choose a programming language
