Update Python lab instructions with integrated auth

solliancenet · Dec 12, 2024 · 6f3c7d3 · 6f3c7d3
1 parent 2d011ca
commit 6f3c7d3
Show file tree

Hide file tree

Showing 5 changed files with 127 additions and 56 deletions.
diff --git a/python/instructions/01-sdk-connect.md b/python/instructions/01-sdk-connect.md
@@ -45,6 +45,12 @@ The **azure-cosmos** library is available on **PyPI** for easy installation into
     pip install azure-cosmos
     ```
 
+1. Install the [azure-identity][pypi.org/project/azure-identity] library, which allows us to use Azure authentication to connect to the Azure Cosmos DB workspace, using the following command:
+
+    ```bash
+    pip install azure-identity
+    ```
+
 1. Close the integrated terminal.
 
 ## Use the azure-cosmos library
@@ -55,27 +61,26 @@ Once the Azure Cosmos DB library from the Azure SDK for Python has been imported
 
 1. Open the blank Python file named **script.py**.
 
-1. Add the following `import` statement to import the **CosmosClient** class:
+1. Add the following `import` statement to import the **CosmosClient** and the **DefaultAzureCredential** classes:
 
     ```python
     from azure.cosmos import CosmosClient
+    from azure.identity import DefaultAzureCredential
     ```
 
-1. Add variables named **endpoint** and **key** and set their values to the **endpoint** and **key** of the Azure Cosmos DB account you created earlier.
+1. Add variables named **endpoint** and **credential** and set the **endpoint** value to the **endpoint** of the Azure Cosmos DB account you created earlier. The **credential** variable should be set to a new instance of the **DefaultAzureCredential** class:
 
     ```python
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
     ```
 
     > &#128221; For example, if your endpoint is: **https://dp420.documents.azure.com:443/**, the statement would be: **endpoint = "https://dp420.documents.azure.com:443/"**.
 
-    > &#128221; If your key is: **fDR2ci9QgkdkvERTQ==**, the statement would be: **key = "fDR2ci9QgkdkvERTQ=="**.
-
-1. Add a new variable named **client** and initialize it as a new instance of the **CosmosClient** class using the **endpoint** and **key** variables:
+1. Add a new variable named **client** and initialize it as a new instance of the **CosmosClient** class using the **endpoint** and **credential** variables:
 
     ```python
-    client = CosmosClient(endpoint, key)
+    client = CosmosClient(endpoint, credential=credential)
     ```
 
 1. Add a function named **main** to read and print account properties:
@@ -94,9 +99,10 @@ Once the Azure Cosmos DB library from the Azure SDK for Python has been imported
 
     ```python
     from azure.cosmos import CosmosClient
+    from azure.identity import DefaultAzureCredential
 
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
 
     client = CosmosClient(endpoint, key)
 
@@ -117,6 +123,12 @@ Now that the Python code to connect to the Azure Cosmos DB for NoSQL account is
 
 1. In **Visual Studio Code**, open the context menu for the **python/01-sdk-connect** folder and then select **Open in Integrated Terminal** to open a new terminal instance.
 
+1. Before running the script, you must log into Azure using the `az login` command. At the terminal window, run:
+
+    ```azurecli
+    az login
+    ```
+
 1. Run the script using the `python` command:
 
     ```bash
@@ -135,3 +147,4 @@ Now that the Python code to connect to the Azure Cosmos DB for NoSQL account is
 1. Close **Visual Studio Code**.
 
 [pypi.org/project/azure-cosmos]: https://pypi.org/project/azure-cosmos
+[pypi.org/project/azure-identity]: https://pypi.org/project/azure-identity
diff --git a/python/instructions/03-sdk-crud.md b/python/instructions/03-sdk-crud.md
@@ -57,6 +57,12 @@ The **azure-cosmos** library is available on **PyPI** for easy installation into
     pip install aiohttp
     ```
 
+1. Install the [azure-identity][pypi.org/project/azure-identity] library, which allows us to use Azure authentication to connect to the Azure Cosmos DB workspace, using the following command:
+
+    ```bash
+    pip install azure-identity
+    ```
+
 ## Use the azure-cosmos library
 
 Using the credentials from the newly created account, you will connect with the SDK classes and create a new database and container instance. Then, you will use the Data Explorer to validate that the instances exist in the Azure portal.
@@ -71,29 +77,28 @@ Using the credentials from the newly created account, you will connect with the
     from azure.cosmos import PartitionKey
     ```
 
-1. Add the following `import` statements to import the asynchronous **CosmosClient** class and the **asyncio** library:
+1. Add the following `import` statements to import the asynchronous **CosmosClient** class, **DefaultAzureCredential** class, and the **asyncio** library:
 
     ```python
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
     ```
 
-1. Add variables named **endpoint** and **key** and set their values to the **endpoint** and **key** of the Azure Cosmos DB account you created earlier.
+1. Add variables named **endpoint** and **credential** and set the **endpoint** value to the **endpoint** of the Azure Cosmos DB account you created earlier. The **credential** variable should be set to a new instance of the **DefaultAzureCredential** class:
 
     ```python
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
     ```
 
     > &#128221; For example, if your endpoint is: **https://dp420.documents.azure.com:443/**, the statement would be: **endpoint = "https://dp420.documents.azure.com:443/"**.
 
-    > &#128221; If your key is: **fDR2ci9QgkdkvERTQ==**, the statement would be: **key = "fDR2ci9QgkdkvERTQ=="**.
-
-1. All interaction with Cosmos DB starts with an instance of the `CosmosClient`. In order to use the asynchronous client, we need to use async/await keywords, which can only be used within async methods. Create a new async method named **main** and add the following code to create a new instance of the asynchronous **CosmosClient** class using the **endpoint** and **key** variables:
+1. All interaction with Cosmos DB starts with an instance of the `CosmosClient`. In order to use the asynchronous client, we need to use async/await keywords, which can only be used within async methods. Create a new async method named **main** and add the following code to create a new instance of the asynchronous **CosmosClient** class using the **endpoint** and **credential** variables:
 
     ```python
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
     ```
 
     > &#128161; Since we're using the asynchronous **CosmosClient** client, in order to properly use it you also have to warm it up and close it down. We recommend using the `async with` keywords as demonstrated in the code above to start your clients - these keywords create a context manager that automatically warms up, initializes, and cleans up the client, so you don't have to.
@@ -124,13 +129,14 @@ Using the credentials from the newly created account, you will connect with the
     ```python
     from azure.cosmos import PartitionKey
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
 
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
 
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
             # Create database
             database = await client.create_database_if_not_exists(id="cosmicworks")
     
@@ -146,6 +152,12 @@ Using the credentials from the newly created account, you will connect with the
 
 1. **Save** the **script.py** file.
 
+1. Before running the script, you must log into Azure using the `az login` command. At the terminal window, run:
+
+    ```azurecli
+    az login
+    ```
+
 1. Run the script to create the database and container:
 
     ```bash
@@ -195,13 +207,14 @@ You will now use the set of methods in the **ContainerProxy** class to perform c
     ```python
     from azure.cosmos import PartitionKey
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
 
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
 
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
             # Create database
             database = await client.create_database_if_not_exists(id="cosmicworks")
     
@@ -283,13 +296,14 @@ You will now use the set of methods in the **ContainerProxy** class to perform c
     ```python
     from azure.cosmos import PartitionKey
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
 
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
 
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
             # Create database
             database = await client.create_database_if_not_exists(id="cosmicworks")
     
@@ -369,13 +383,14 @@ While learning the SDK, it's not uncommon to use an online Azure Cosmos DB accou
     ```python
     from azure.cosmos import PartitionKey
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
 
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
 
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
             # Create database
             database = await client.create_database_if_not_exists(id="cosmicworks")
     
@@ -464,3 +479,4 @@ While learning the SDK, it's not uncommon to use an online Azure Cosmos DB accou
 
 [code.visualstudio.com/docs/getstarted]: https://code.visualstudio.com/docs/getstarted/tips-and-tricks
 [pypi.org/project/azure-cosmos]: https://pypi.org/project/azure-cosmos
+[pypi.org/project/azure-identity]: https://pypi.org/project/azure-identity
diff --git a/python/instructions/04-sdk-batch.md b/python/instructions/04-sdk-batch.md
@@ -57,6 +57,12 @@ The **azure-cosmos** library is available on **PyPI** for easy installation into
     pip install aiohttp
     ```
 
+1. Install the [azure-identity][pypi.org/project/azure-identity] library, which allows us to use Azure authentication to connect to the Azure Cosmos DB workspace, using the following command:
+
+    ```bash
+    pip install azure-identity
+    ```
+
 ## Use the azure-cosmos library
 
 Using the credentials from the newly created account, you will connect with the SDK classes and create a new database and container instance. Then, you will use the Data Explorer to validate that the instances exist in the Azure portal.
@@ -71,29 +77,28 @@ Using the credentials from the newly created account, you will connect with the
     from azure.cosmos import PartitionKey
     ```
 
-1. Add the following `import` statements to import the asynchronous **CosmosClient** class and the **asyncio** library:
+1. Add the following `import` statements to import the asynchronous **CosmosClient** class, **DefaultAzureCredential** class, and the **asyncio** library:
 
     ```python
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
     ```
 
-1. Add variables named **endpoint** and **key** and set their values to the **endpoint** and **key** of the Azure Cosmos DB account you created earlier.
+1. Add variables named **endpoint** and **credential** and set the **endpoint** value to the **endpoint** of the Azure Cosmos DB account you created earlier. The **credential** variable should be set to a new instance of the **DefaultAzureCredential** class:
 
     ```python
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
     ```
 
     > &#128221; For example, if your endpoint is: **https://dp420.documents.azure.com:443/**, the statement would be: **endpoint = "https://dp420.documents.azure.com:443/"**.
 
-    > &#128221; If your key is: **fDR2ci9QgkdkvERTQ==**, the statement would be: **key = "fDR2ci9QgkdkvERTQ=="**.
-
-1. All interaction with Cosmos DB starts with an instance of the `CosmosClient`. In order to use the asynchronous client, we need to use async/await keywords, which can only be used within async methods. Create a new async method named **main** and add the following code to create a new instance of the asynchronous **CosmosClient** class using the **endpoint** and **key** variables:
+1. All interaction with Cosmos DB starts with an instance of the `CosmosClient`. In order to use the asynchronous client, we need to use async/await keywords, which can only be used within async methods. Create a new async method named **main** and add the following code to create a new instance of the asynchronous **CosmosClient** class using the **endpoint** and **credential** variables:
 
     ```python
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
     ```
 
     > &#128161; Since we're using the asynchronous **CosmosClient** client, in order to properly use it you also have to warm it up and close it down. We recommend using the `async with` keywords as demonstrated in the code above to start your clients - these keywords create a context manager that automatically warms up, initializes, and cleans up the client, so you don't have to.
@@ -124,13 +129,14 @@ Using the credentials from the newly created account, you will connect with the
     ```python
     from azure.cosmos import exceptions, PartitionKey
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
 
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
 
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
             # Create database
             database = await client.create_database_if_not_exists(id="cosmicworks")
     
@@ -146,6 +152,12 @@ Using the credentials from the newly created account, you will connect with the
 
 1. **Save** the **script.py** file.
 
+1. Before running the script, you must log into Azure using the `az login` command. At the terminal window, run:
+
+    ```azurecli
+    az login
+    ```
+
 1. Run the script to create the database and container:
 
     ```bash
@@ -214,13 +226,14 @@ try:
     ```python
     from azure.cosmos import exceptions, PartitionKey
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
 
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
 
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
             # Create database
             database = await client.create_database_if_not_exists(id="cosmicworks")
     
@@ -319,13 +332,14 @@ Now, let’s create a transactional batch that will error purposefully. This bat
     ```python
     from azure.cosmos import exceptions, PartitionKey
     from azure.cosmos.aio import CosmosClient
+    from azure.identity.aio import DefaultAzureCredential
     import asyncio
 
     endpoint = "<cosmos-endpoint>"
-    key = "<cosmos-key>"
+    credential = DefaultAzureCredential()
 
     async def main():
-        async with CosmosClient(endpoint, credential=key) as client:
+        async with CosmosClient(endpoint, credential=credential) as client:
             # Create database
             database = await client.create_database_if_not_exists(id="cosmicworks")
     
@@ -381,3 +395,4 @@ Now, let’s create a transactional batch that will error purposefully. This bat
 
 [code.visualstudio.com/docs/getstarted]: https://code.visualstudio.com/docs/getstarted/tips-and-tricks
 [pypi.org/project/azure-cosmos]: https://pypi.org/project/azure-cosmos
+[pypi.org/project/azure-identity]: https://pypi.org/project/azure-identity