Skip to content

Commit

Permalink
Merge branch 'main' of https://github.com/solliancenet/microsoft-lear…
Browse files Browse the repository at this point in the history 
…ning-path-build-copilots-with-cosmos-db-labs
  • Loading branch information
@kylebunting
kylebunting committed Dec 26, 2024
2 parents 7c59d6c + 7e34f53 commit c3c0090
Show file tree
Hide file tree
Showing 17 changed files with 1,971 additions and 1,822 deletions.
42 changes: 20 additions & 22 deletions common/instructions/00-setup-cosmos-db.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ Azure Cosmos DB is a cloud-based NoSQL database service that supports multiple A

1. In a new web browser window or tab, navigate to the Azure portal (``portal.azure.com``).

2. Sign into the portal using the Microsoft credentials associated with your subscription.
1. Sign into the portal using the Microsoft credentials associated with your subscription.

3. Select **+ Create a resource**, search for *Cosmos DB*, and then create a new **Azure Cosmos DB for NoSQL** account resource with the following settings, leaving all remaining settings to their default values:
1. Select **+ Create a resource**, search for *Cosmos DB*, and then create a new **Azure Cosmos DB for NoSQL** account resource with the following settings, leaving all remaining settings to their default values:

| **Setting** | **Value** |
| ---: | :--- |
Expand All @@ -33,9 +33,15 @@ Azure Cosmos DB is a cloud-based NoSQL database service that supports multiple A

> 📝 Your lab environments may have restrictions preventing you from creating a new resource group. If that is the case, use the existing pre-created resource group.
4. Wait for the deployment task to complete before continuing with this task.
1. Wait for the deployment task to complete before continuing with this task.

5. Keep the browser tab open for the next step.
1. Go to the newly created **Azure Cosmos DB** account resource and navigate to the **Keys** pane.

1. This pane contains the connection details and credentials necessary to connect to the account from the SDK. Specifically:

1. Copy the **URI** field and save it in a text editor for later. You will use this **endpoint** value later in this exercise.

1. Keep the browser tab open for the next step.

## Provide your user identity the Cosmos DB Built-in Data Contributor RBAC role

Expand All @@ -47,34 +53,26 @@ As the final task in this exercise, you will grant your Microsoft Entra ID user

![The Cloud Shell icon is highlighted on the Azure portal's toolbar.](media/azure-portal-toolbar-cloud-shell.png)

2. At the Cloud Shell prompt, ensure your exercise subscription is used for subsequent commands by running `az account set -s <SUBSCRIPTION_ID>`, replacing the `<SUBSCRIPTION_ID>` placeholder token with the id of the subscription you are using for this exercise.

3. Before assigning your account to the **Cosmos DB Built-in Data Contributor** RBAC role, you must retrieve your Entra ID user identity object ID using the Azure CLI. Execute the following command a the Cloud Shell prompt, replacing the `<USER_PRINCIPAL_NAME>` with your user principal name (e.g., an email address like `[email protected]`).

```azurecli
az ad user show --id <USER_PRINCIPAL_NAME> --query id --output tsv
```
The above command returns object ID associated with your user identity.
1. At the Cloud Shell prompt, ensure your exercise subscription is used for subsequent commands by running `az account set -s <SUBSCRIPTION_ID>`, replacing the `<SUBSCRIPTION_ID>` placeholder token with the id of the subscription you are using for this exercise.

4. Copy the output of the above command for use as the `<PRINCIPAL_OBJECT_ID>` token in the `az cosmosdb sql role assignment create` command below.
1. Copy the output of the above command for use as the `<PRINCIPAL_OBJECT_ID>` token in the `az cosmosdb sql role assignment create` command below.

5. Next, you will retrieve the definition id of the **Cosmos DB Built-in Data Contributor** role. Run the following command, ensuring you replace the `<RESOURCE_GROUP_NAME>` and `<COSMOS_DB_ACCOUNT_NAME>` tokens.
1. Next, you will retrieve the definition id of the **Cosmos DB Built-in Data Contributor** role. Run the following command, ensuring you replace the `<RESOURCE_GROUP_NAME>` and `<COSMOS_DB_ACCOUNT_NAME>` tokens.

```azurecli
```bash
az cosmosdb sql role definition list --resource-group "<RESOURCE_GROUP_NAME>" --account-name "<COSMOS_DB_ACCOUNT_NAME>"
```

Review the output and locate the role definition named **Cosmos DB Built-in Data Contributor**. The output contains the unique identifier of the role definition in the `name` property. Record this value as it is required to use in the assignment step later in the next step.

6. You are now ready to assign yourself to the **Cosmos DB Built-in Data Contributor** role definition. Enter the following command at the prompt, making sure to replace the `<RESOURCE_GROUP_NAME>`, `<COSMOS_DB_ACCOUNT_NAME>`, and `<PRINCIPAL_OBJECT_ID>` tokens.
1. You are now ready to assign yourself to the **Cosmos DB Built-in Data Contributor** role definition. Enter the following command at the prompt, making sure to replace the `<RESOURCE_GROUP_NAME>` and `<COSMOS_DB_ACCOUNT_NAME>` tokens.

> &#128221; In the command below, the `role-definition-id` is set to `00000000-0000-0000-0000-000000000002`, which is the default value for the **Cosmos DB Built-in Data Contributor** role definition. If the value you retrieved from the `az cosmosdb sql role definition list` command differs, replace the value in the command below before execution.
> &#128221; In the command below, the `role-definition-id` is set to `00000000-0000-0000-0000-000000000002`, which is the default value for the **Cosmos DB Built-in Data Contributor** role definition. If the value you retrieved from the `az cosmosdb sql role definition list` command differs, replace the value in the command below before execution. The `az ad signed-in-user show` command retrieves the object ID of the signed-in Entra ID user.

```azurecli
az cosmosdb sql role assignment create --resource-group "<RESOURCE_GROUP_NAME>" --account-name "<COSMOS_DB_ACCOUNT_NAME>" --role-definition-id "00000000-0000-0000-0000-000000000002" --principal-id "<PRINCIPAL_OBJECT_ID>" --scope "/"
```bash
az cosmosdb sql role assignment create --resource-group "<RESOURCE_GROUP_NAME>" --account-name "<COSMOS_DB_ACCOUNT_NAME>" --role-definition-id "00000000-0000-0000-0000-000000000002" --principal-id $(az ad signed-in-user show --query id -o tsv) --scope "/"
```

7. When the command finishes running, you will be able to run code locally to insert interact with data stored into the your Cosmos DB NoSQL database.
1. When the command finishes running, you will be able to run code locally to insert interact with data stored into the your Cosmos DB NoSQL database.

8. Close the Cloud Shell.
1. Close the Cloud Shell.
33 changes: 23 additions & 10 deletions javascript/instructions/01-sdk-connect.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,11 @@ The **@azure/cosmos** library is available on **npm** for easy installation into
npm install @azure/cosmos
```

1. Close the integrated terminal.
1. Install the [@azure/identity][npmjs.com/package/@azure/identity] library, which allows us to use Azure authentication to connect to the Azure Cosmos DB workspace, using the following command:

```bash
npm install @azure/identity
```

## Use the @azure/cosmos library

Expand All @@ -54,27 +58,27 @@ Once the Azure Cosmos DB library from the Azure SDK for JavaScript has been impo

1. Open the empty JavaScript file named **script.js**.

1. Add the following `require` statement to import the **@azure/cosmos** library:
1. Add the following `require` statements to import the **@azure/cosmos** and **@azure/identity** libraries:

```javascript
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0
```
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:
```javascript
const endpoint = "<cosmos-endpoint>";
const key = "<cosmos-key>";
const credential = new DefaultAzureCredential();
```
> &#128221; For example, if your endpoint is: **https://dp420.documents.azure.com:443/**, the statement would be: **const endpoint = "https://dp420.documents.azure.com:443/";**.
> &#128221; If your key is: **fDR2ci9QgkdkvERTQ==**, the statement would be: **const 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:
```javascript
const client = new CosmosClient({ endpoint, key });
const client = new CosmosClient({ endpoint, aadCredentials: credential });
```
1. Add an `async` function named **main** to read and print account properties:
Expand All @@ -97,11 +101,13 @@ Once the Azure Cosmos DB library from the Azure SDK for JavaScript has been impo
```javascript
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0
const endpoint = "<cosmos-endpoint>";
const key = "<cosmos-key>";
const credential = new DefaultAzureCredential();
const client = new CosmosClient({ endpoint, key });
const client = new CosmosClient({ endpoint, aadCredentials: credential });
async function main() {
const { resource: account } = await client.getDatabaseAccount();
Expand All @@ -120,6 +126,12 @@ Now that the JavaScript code to connect to the Azure Cosmos DB for NoSQL account
1. In **Visual Studio Code**, open the context menu for the **javascript/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:
```bash
az login
```
1. Run the script using the `node` command:
```bash
Expand All @@ -139,3 +151,4 @@ Now that the JavaScript code to connect to the Azure Cosmos DB for NoSQL account
[code.visualstudio.com/docs/getstarted]: https://code.visualstudio.com/docs/getstarted/tips-and-tricks
[npmjs.com/package/@azure/cosmos]: https://www.npmjs.com/package/@azure/cosmos
[npmjs.com/package/@azure/identity]: https://www.npmjs.com/package/@azure/identity
54 changes: 35 additions & 19 deletions javascript/instructions/03-sdk-crud.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,12 @@ The **@azure/cosmos** library is available on **npm** for easy installation into
npm install @azure/cosmos
```

1. Install the [@azure/identity][npmjs.com/package/@azure/identity] library, which allows us to use Azure authentication to connect to the Azure Cosmos DB workspace, using the following command:

```bash
npm install @azure/identity
```

## Use the @azure/cosmos library

Once the Azure Cosmos DB library from the Azure SDK for JavaScript has been imported, you can immediately use its classes to connect to an Azure Cosmos DB for NoSQL account. The **CosmosClient** class is the core class used to make the initial connection to an Azure Cosmos DB for NoSQL account.
Expand All @@ -52,28 +58,27 @@ Once the Azure Cosmos DB library from the Azure SDK for JavaScript has been impo

1. Open the empty JavaScript file named **script.js**.

1. Add the following `require` statement to import the **@azure/cosmos** library:
1. Add the following `require` statements to import the **@azure/cosmos** and **@azure/identity** libraries:

```javascript
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0
```
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:
```javascript
const endpoint = "<cosmos-endpoint>";
const key = "<cosmos-key>";
const credential = new DefaultAzureCredential();
```
> &#128221; For example, if your endpoint is: **https://dp420.documents.azure.com:443/**, the statement would be: **const endpoint = "https://dp420.documents.azure.com:443/";**.
> &#128221; If your key is: **fDR2ci9QgkdkvERTQ==**, the statement would be: **const 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:
```javascript
const client = new CosmosClient({ endpoint, key });
const client = new CosmosClient({ endpoint, aadCredentials: credential });
```
1. Add the following code to create a database and container if they do not already exist:
Expand All @@ -98,12 +103,13 @@ Once the Azure Cosmos DB library from the Azure SDK for JavaScript has been impo
```javascript
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0
const endpoint = "<cosmos-endpoint>";
const key = "<cosmos-key>";
const credential = new DefaultAzureCredential();
const client = new CosmosClient({ endpoint, key });
const client = new CosmosClient({ endpoint, aadCredentials: credential });
async function main() {
// Create database
Expand All @@ -122,6 +128,12 @@ Once the Azure Cosmos DB library from the Azure SDK for JavaScript has been impo
1. **Save** the **script.js** file.
1. Before running the script, you must log into Azure using the `az login` command. At the terminal window, run:
```bash
az login
```
1. Run the script to create the database and container:
```bash
Expand Down Expand Up @@ -171,12 +183,13 @@ You will now use the set of methods in the **Container** class to perform common
```javascript
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0
const endpoint = "<cosmos-endpoint>";
const key = "<cosmos-key>";
const credential = new DefaultAzureCredential();
const client = new CosmosClient({ endpoint, key });
const client = new CosmosClient({ endpoint, aadCredentials: credential });
async function main() {
// Create database
Expand Down Expand Up @@ -262,12 +275,13 @@ You will now use the set of methods in the **Container** class to perform common
```javascript
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0
const endpoint = "<cosmos-endpoint>";
const key = "<cosmos-key>";
const client = new CosmosClient({ endpoint, key });
const credential = new DefaultAzureCredential();
const client = new CosmosClient({ endpoint, aadCredentials: credential });
async function main() {
// Create database
Expand Down Expand Up @@ -350,12 +364,13 @@ While learning the SDK, it's not uncommon to use an online Azure Cosmos DB accou
```javascript
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0
const endpoint = "<cosmos-endpoint>";
const key = "<cosmos-key>";
const client = new CosmosClient({ endpoint, key });
const credential = new DefaultAzureCredential();
const client = new CosmosClient({ endpoint, aadCredentials: credential });
async function main() {
// Create database
Expand Down Expand Up @@ -449,3 +464,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
[npmjs.com/package/@azure/cosmos]: https://www.npmjs.com/package/@azure/cosmos
[npmjs.com/package/@azure/identity]: https://www.npmjs.com/package/@azure/identity
Loading

0 comments on commit c3c0090

Please sign in to comment.