Skip to content

Commit 36cafb3

Browse files
Court72Court72
authored
Merge pull request #211470 from diberry/diberry/0915-cosmos-quickstart
Cosmos DB Core (SQL) JS Quickstart update
2 parents 6ecd10a + fbdf93a commit 36cafb3

File tree

7 files changed

+486
-382
lines changed

7 files changed

+486
-382
lines changed

‎.openpublishing.publish.config.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -674,6 +674,12 @@
674674
"branch": "main",
675675
"branch_mapping": {}
676676
},
677+
{
678+
"path_to_root": "cosmos-db-sql-api-javascript-samples",
679+
"url": "https://github.com/Azure-Samples/cosmos-db-sql-api-javascript-samples",
680+
"branch": "main",
681+
"branch_mapping": {}
682+
},
677683
{
678684
"path_to_root": "azure-cosmos-db-python-getting-started",
679685
"url": "https://github.com/Azure-Samples/azure-cosmos-db-python-getting-started",

‎articles/cosmos-db/sql/create-sql-api-nodejs.md

Lines changed: 142 additions & 101 deletions
Large diffs are not rendered by default.

‎articles/cosmos-db/sql/includes/environment-variables.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: cosmos-db
5+
author: seesharprun
6+
ms.service: cosmos-db
7+
ms.topic: include
8+
ms.date: 09/15/2022
9+
ms.author: sidandrews
10+
ms.reviewer: mjbrown
11+
ms.custom: include file
12+
---
13+
14+
To use the **URI** and **PRIMARY KEY** values within your code, persist them to new environment variables on the local machine running the application. To set the environment variable, use your preferred terminal to run the following commands:
15+
16+
#### [Windows](#tab/windows)
17+
18+
```powershell
19+
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
20+
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
21+
```
22+
23+
#### [Linux / macOS](#tab/linux+macos)
24+
25+
```bash
26+
export COSMOS_ENDPOINT="<cosmos-account-URI>"
27+
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"
28+
```
29+
30+
---

‎articles/cosmos-db/sql/includes/quickstart-arm.md

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: cosmos-db
5+
author: seesharprun
6+
ms.service: cosmos-db
7+
ms.topic: include
8+
ms.date: 09/15/2022
9+
ms.author: sidandrews
10+
ms.reviewer: mjbrown
11+
ms.custom: include file
12+
---
13+
14+
15+
This quickstart will create a single Azure Cosmos DB account using the SQL API.
16+
17+
#### [Azure CLI](#tab/azure-cli)
18+
19+
1. Create shell variables for *accountName*, *resourceGroupName*, and *location*.
20+
21+
```azurecli-interactive
22+
# Variable for resource group name
23+
resourceGroupName="msdocs-cosmos-quickstart-rg"
24+
location="westus"
25+
26+
# Variable for account name with a randomly generated suffix
27+
let suffix=$RANDOM*$RANDOM
28+
accountName="msdocs-$suffix"
29+
```
30+
31+
1. If you haven't already, sign in to the Azure CLI using the [``az login``](/cli/azure/reference-index#az-login) command.
32+
33+
1. Use the [``az group create``](/cli/azure/group#az-group-create) command to create a new resource group in your subscription.
34+
35+
```azurecli-interactive
36+
az group create \
37+
--name $resourceGroupName \
38+
--location $location
39+
```
40+
41+
1. Use the [``az cosmosdb create``](/cli/azure/cosmosdb#az-cosmosdb-create) command to create a new Azure Cosmos DB SQL API account with default settings.
42+
43+
```azurecli-interactive
44+
az cosmosdb create \
45+
--resource-group $resourceGroupName \
46+
--name $accountName \
47+
--locations regionName=$location
48+
```
49+
50+
1. Get the SQL API endpoint *URI* for the account using the [``az cosmosdb show``](/cli/azure/cosmosdb#az-cosmosdb-show) command.
51+
52+
```azurecli-interactive
53+
az cosmosdb show \
54+
--resource-group $resourceGroupName \
55+
--name $accountName \
56+
--query "documentEndpoint"
57+
```
58+
59+
1. Find the *PRIMARY KEY* from the list of keys for the account with the [`az-cosmosdb-keys-list`](/cli/azure/cosmosdb/keys#az-cosmosdb-keys-list) command.
60+
61+
```azurecli-interactive
62+
az cosmosdb keys list \
63+
--resource-group $resourceGroupName \
64+
--name $accountName \
65+
--type "keys" \
66+
--query "primaryMasterKey"
67+
```
68+
69+
1. Record the *URI* and *PRIMARY KEY* values. You'll use these credentials later.
70+
71+
#### [PowerShell](#tab/azure-powershell)
72+
73+
1. Create shell variables for *ACCOUNT_NAME*, *RESOURCE_GROUP_NAME*, and **LOCATION**.
74+
75+
```azurepowershell-interactive
76+
# Variable for resource group name
77+
$RESOURCE_GROUP_NAME = "msdocs-cosmos-quickstart-rg"
78+
$LOCATION = "West US"
79+
80+
# Variable for account name with a randomly generated suffix
81+
$SUFFIX = Get-Random
82+
$ACCOUNT_NAME = "msdocs-$SUFFIX"
83+
```
84+
85+
1. If you haven't already, sign in to Azure PowerShell using the [``Connect-AzAccount``](/powershell/module/az.accounts/connect-azaccount) cmdlet.
86+
87+
1. Use the [``New-AzResourceGroup``](/powershell/module/az.resources/new-azresourcegroup) cmdlet to create a new resource group in your subscription.
88+
89+
```azurepowershell-interactive
90+
$parameters = @{
91+
Name = $RESOURCE_GROUP_NAME
92+
Location = $LOCATION
93+
}
94+
New-AzResourceGroup @parameters
95+
```
96+
97+
1. Use the [``New-AzCosmosDBAccount``](/powershell/module/az.cosmosdb/new-azcosmosdbaccount) cmdlet to create a new Azure Cosmos DB SQL API account with default settings.
98+
99+
```azurepowershell-interactive
100+
$parameters = @{
101+
ResourceGroupName = $RESOURCE_GROUP_NAME
102+
Name = $ACCOUNT_NAME
103+
Location = $LOCATION
104+
}
105+
New-AzCosmosDBAccount @parameters
106+
```
107+
108+
1. Get the SQL API endpoint *URI* for the account using the [``Get-AzCosmosDBAccount``](/powershell/module/az.cosmosdb/get-azcosmosdbaccount) cmdlet.
109+
110+
```azurepowershell-interactive
111+
$parameters = @{
112+
ResourceGroupName = $RESOURCE_GROUP_NAME
113+
Name = $ACCOUNT_NAME
114+
}
115+
Get-AzCosmosDBAccount @parameters |
116+
Select-Object -Property "DocumentEndpoint"
117+
```
118+
119+
1. Find the *PRIMARY KEY* from the list of keys for the account with the [``Get-AzCosmosDBAccountKey``](/powershell/module/az.cosmosdb/get-azcosmosdbaccountkey) cmdlet.
120+
121+
```azurepowershell-interactive
122+
$parameters = @{
123+
ResourceGroupName = $RESOURCE_GROUP_NAME
124+
Name = $ACCOUNT_NAME
125+
Type = "Keys"
126+
}
127+
Get-AzCosmosDBAccountKey @parameters |
128+
Select-Object -Property "PrimaryMasterKey"
129+
```
130+
131+
1. Record the *URI* and *PRIMARY KEY* values. You'll use these credentials later.
132+
133+
#### [Portal](#tab/azure-portal)
134+
135+
> [!TIP]
136+
> For this quickstart, we recommend using the resource group name ``msdocs-cosmos-quickstart-rg``.
137+
138+
1. Sign in to the [Azure portal](https://portal.azure.com).
139+
140+
1. From the Azure portal menu or the **Home page**, select **Create a resource**.
141+
142+
1. On the **New** page, search for and select **Azure Cosmos DB**.
143+
144+
1. On the **Select API option** page, select the **Create** option within the **Core (SQL) - Recommend** section. Azure Cosmos DB has five APIs: SQL, MongoDB, Gremlin, Table, and Cassandra. [Learn more about the SQL API](../index.yml).
145+
146+
:::image type="content" source="../media/create-account-portal/cosmos-api-choices.png" lightbox="../media/create-account-portal/cosmos-api-choices.png" alt-text="Screenshot of select API option page for Azure Cosmos DB.":::
147+
148+
1. On the **Create Azure Cosmos DB Account** page, enter the following information:
149+
150+
| Setting | Value | Description |
151+
| --- | --- | --- |
152+
| Subscription | Subscription name | Select the Azure subscription that you wish to use for this Azure Cosmos account. |
153+
| Resource Group | Resource group name | Select a resource group, or select **Create new**, then enter a unique name for the new resource group. |
154+
| Account Name | A unique name | Enter a name to identify your Azure Cosmos account. The name will be used as part of a fully qualified domain name (FQDN) with a suffix of *documents.azure.com*, so the name must be globally unique. The name can only contain lowercase letters, numbers, and the hyphen (-) character. The name must also be between 3-44 characters in length. |
155+
| Location | The region closest to your users | Select a geographic location to host your Azure Cosmos DB account. Use the location that is closest to your users to give them the fastest access to the data. |
156+
| Capacity mode |Provisioned throughput or Serverless|Select **Provisioned throughput** to create an account in [provisioned throughput](../../set-throughput.md) mode. Select **Serverless** to create an account in [serverless](../../serverless.md) mode. |
157+
| Apply Azure Cosmos DB free tier discount | **Apply** or **Do not apply** |With Azure Cosmos DB free tier, you'll get the first 1000 RU/s and 25 GB of storage for free in an account. Learn more about [free tier](https://azure.microsoft.com/pricing/details/cosmos-db/). |
158+
159+
> [!NOTE]
160+
> You can have up to one free tier Azure Cosmos DB account per Azure subscription and must opt-in when creating the account. If you do not see the option to apply the free tier discount, this means another account in the subscription has already been enabled with free tier.
161+
162+
:::image type="content" source="../media/create-account-portal/new-cosmos-account-page.png" lightbox="../media/create-account-portal/new-cosmos-account-page.png" alt-text="Screenshot of new account page for Azure Cosmos DB SQL API.":::
163+
164+
1. Select **Review + create**.
165+
166+
1. Review the settings you provide, and then select **Create**. It takes a few minutes to create the account. Wait for the portal page to display **Your deployment is complete** before moving on.
167+
168+
1. Select **Go to resource** to go to the Azure Cosmos DB account page.
169+
170+
:::image type="content" source="../media/create-account-portal/cosmos-deployment-complete.png" lightbox="../media/create-account-portal/cosmos-deployment-complete.png" alt-text="Screenshot of deployment page for Azure Cosmos DB SQL API resource.":::
171+
172+
1. From the Azure Cosmos DB SQL API account page, select the **Keys** navigation menu option.
173+
174+
:::image type="content" source="../media/get-credentials-portal/cosmos-keys-option.png" lightbox="../media/get-credentials-portal/cosmos-keys-option.png" alt-text="Screenshot of an Azure Cosmos DB SQL API account page. The Keys option is highlighted in the navigation menu.":::
175+
176+
1. Record the values from the **URI** and **PRIMARY KEY** fields. You'll use these values in a later step.
177+
178+
:::image type="content" source="../media/get-credentials-portal/cosmos-endpoint-key-credentials.png" lightbox="../media/get-credentials-portal/cosmos-endpoint-key-credentials.png" alt-text="Screenshot of Keys page with various credentials for an Azure Cosmos DB SQL API account.":::
179+
180+
#### [Resource Manager template](#tab/azure-resource-manager)
181+
182+
> [!NOTE]
183+
> Azure Resource Manager templates are written in two syntaxes, JSON and Bicep. This sample uses the [Bicep](../../../azure-resource-manager/bicep/overview.md) syntax. To learn more about the two syntaxes, see [comparing JSON and Bicep for templates](../../../azure-resource-manager/bicep/compare-template-syntax.md).
184+
185+
1. Create shell variables for *accountName*, *resourceGroupName*, and *location*.
186+
187+
```azurecli-interactive
188+
# Variable for resource group name
189+
resourceGroupName="msdocs-cosmos"
190+
191+
# Variable for location
192+
location="westus"
193+
194+
# Variable for account name with a randomly generated suffix
195+
let suffix=$RANDOM*$RANDOM
196+
accountName="msdocs-$suffix"
197+
```
198+
199+
1. If you haven't already, sign in to the Azure CLI using the [``az login``](/cli/azure/reference-index#az-login) command.
200+
201+
1. Use the [``az group create``](/cli/azure/group#az-group-create) command to create a new resource group in your subscription.
202+
203+
```azurecli-interactive
204+
az group create \
205+
--name $resourceGroupName \
206+
--location $location
207+
```
208+
209+
1. Create a new ``.bicep`` file with the deployment template in the Bicep syntax.
210+
211+
:::code language="bicep" source="~/quickstart-templates/quickstarts/microsoft.documentdb/cosmosdb-sql-minimal/main.bicep":::
212+
213+
1. Deploy the Azure Resource Manager (ARM) template with [``az deployment group create``](/cli/azure/deployment/group#az-deployment-group-create)
214+
specifying the filename using the **template-file** parameter and the name ``initial-bicep-deploy`` using the **name** parameter.
215+
216+
```azurecli-interactive
217+
az deployment group create \
218+
--resource-group $resourceGroupName \
219+
--name initial-bicep-deploy \
220+
--template-file main.bicep \
221+
--parameters accountName=$accountName
222+
```
223+
224+
> [!NOTE]
225+
> In this example, we assume that the name of the Bicep file is **main.bicep**.
226+
227+
1. Validate the deployment by showing metadata from the newly created account using [``az cosmosdb show``](/cli/azure/cosmosdb#az-cosmosdb-show).
228+
229+
```azurecli-interactive
230+
az cosmosdb show \
231+
--resource-group $resourceGroupName \
232+
--name $accountName
233+
```
234+
235+
---

‎articles/cosmos-db/sql/includes/quickstart-clean-up-resources.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: cosmos-db
5+
author: seesharprun
6+
ms.service: cosmos-db
7+
ms.topic: include
8+
ms.date: 09/15/2022
9+
ms.author: sidandrews
10+
ms.reviewer: mjbrown
11+
ms.custom: include file
12+
---
13+
14+
When you no longer need the Azure Cosmos DB SQL API account, you can delete the corresponding resource group.
15+
16+
### [Azure CLI / Resource Manager template](#tab/azure-cli+azure-resource-manager)
17+
18+
Use the [``az group delete``](/cli/azure/group#az-group-delete) command to delete the resource group.
19+
20+
```azurecli-interactive
21+
az group delete --name $resourceGroupName
22+
```
23+
24+
### [PowerShell](#tab/azure-powershell)
25+
26+
Use the [``Remove-AzResourceGroup``](/powershell/module/az.resources/remove-azresourcegroup) cmdlet to delete the resource group.
27+
28+
```azurepowershell-interactive
29+
$parameters = @{
30+
Name = $RESOURCE_GROUP_NAME
31+
}
32+
Remove-AzResourceGroup @parameters
33+
```
34+
35+
### [Portal](#tab/azure-portal)
36+
37+
1. Navigate to the resource group you previously created in the Azure portal.
38+
39+
> [!TIP]
40+
> In this quickstart, we recommended the name ``msdocs-cosmos-quickstart-rg``.
41+
1. Select **Delete resource group**.
42+
43+
:::image type="content" source="../media/delete-account-portal/delete-resource-group-option.png" lightbox="../media/delete-account-portal/delete-resource-group-option.png" alt-text="Screenshot of the Delete resource group option in the navigation bar for a resource group.":::
44+
45+
1. On the **Are you sure you want to delete** dialog, enter the name of the resource group, and then select **Delete**.
46+
47+
:::image type="content" source="../media/delete-account-portal/delete-confirmation.png" lightbox="../media/delete-account-portal/delete-confirmation.png" alt-text="Screenshot of the delete confirmation page for a resource group.":::
48+
49+
---

‎articles/cosmos-db/sql/includes/quickstart-object-model.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: include file
3+
description: include file
4+
services: cosmos-db
5+
author: seesharprun
6+
ms.service: cosmos-db
7+
ms.topic: include
8+
ms.date: 09/15/2022
9+
ms.author: sidandrews
10+
ms.reviewer: mjbrown
11+
ms.custom: include file
12+
---
13+
14+
Before you start building the application, let's look into the hierarchy of resources in Azure Cosmos DB. Azure Cosmos DB has a specific object model used to create and access resources. The Azure Cosmos DB creates resources in a hierarchy that consists of accounts, databases, containers, and items.
15+
16+
:::image type="complex" source="../media/quickstart-dotnet/resource-hierarchy.svg" alt-text="Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items." border="false":::
17+
Hierarchical diagram showing an Azure Cosmos DB account at the top. The account has two child database nodes. One of the database nodes includes two child container nodes. The other database node includes a single child container node. That single container node has three child item nodes.
18+
:::image-end:::
19+
20+
For more information about the hierarchy of different resources, see [working with databases, containers, and items in Azure Cosmos DB](../../account-databases-containers-items.md).

0 commit comments

Comments
 (0)