Azure Cosmos DB Plugin

The plugin provides functionality to interact with Cosmos DB

Installation

Copy the below line to dependencies section of the project build.gradle file

Please make sure to use the same version for all VIVIDUS dependencies.
Example 1. build.gradle
```
implementation(group: 'org.vividus', name: 'vividus-plugin-azure-cosmos-db', version: '0.6.12')
```
If the project was imported to the IDE before adding new dependency, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.

Configuration

Containers configuration

Containers are configured with a set of properties with the following format:

azure.cosmos-db.container.{container-key}.{property-name}=property value

Where:

container-name - The key of the container configuration
property-name - The name of the container property. One of:
1. container-id - The id of the container
2. db-key - The key of database configuration

azure.cosmos-db.database.{db-key}.{property-name}=property value

Where:

db-key - The key of the database configuration
property-name - The name of the container property. One of:
1. db-id - The id of the container
2. account-key - The key of account configuration

azure.cosmos-db.account.{account-key}.{property-name}=property value

Where:

account-key - The key of the account configuration
property-name - The name of the container property. One of:
1. endpoint - The endpoint of the account.
2. key - Either a master or readonly key used to perform authentication for Cosmos database service. If key is not set, default authentication mechanism described below will be used.
3. connection-mode - https://learn.microsoft.com/en-us/azure/cosmos-db/nosql/sdk-connection-modes [The mechanism], how the client connects to Azure Cosmos DB. Possible values: DIRECT or GATEWAY. If connection-mode is not set, DIRECT will be used.

Example 2. Access configuration

# Container configurations referring database instances via db-key
azure.cosmos-db.container.items.id=Items
azure.cosmos-db.container.items.db-key=main

azure.cosmos-db.container.users.id=Users
azure.cosmos-db.container.users.db-key=main

azure.cosmos-db.container.orders.id=Orders
azure.cosmos-db.container.orders.db-key=commecrial

# Database configurations referring account instances via account-key
azure.cosmos-db.database.main.id=MainDatabase
azure.cosmos-db.database.main.account-key=vividus

azure.cosmos-db.database.commecrial.id=OrdersDb
azure.cosmos-db.database.commecrial.account-key=vividus

# Accounts configuration contains connection details
azure.cosmos-db.account.vividus.endpoint=https://vividus-cosmos.documents.azure.com:443/
azure.cosmos-db.account.vividus.key=some key
azure.cosmos-db.account.vividus.connection-mode=GATEWAY

Authentication

The authentication process relies on the configuration of the environment variables.

See the official "Azure identity" guide to get more details on what types of authentication could be used.

Steps

Read

Read an item by id and partition key

When I read item with `$id` id and `$partition` partition from CosmosDB container `$containerKey` and save result to $scopes variable `$variableName`

$id - The id of the item
$partition - The value of partition key
$containerKey - The key of the container
$scopes - The comma-separated set of the variables scopes.
$variableName - The variable name to store results in JSON format.

Example 3. Read item

When I read item with `1` id and `personal` partition from CosmosDB container `test` and save result to scenario variable `result`
Then JSON element from `${result}` by JSON path `$` is equal to `
{
    "id": "1",
    "category": "personal",
    "name": "groceries",
    "description": "Pick up apples and strawberries.",
    "isComplete": false
}`IGNORING_EXTRA_FIELDS

Execute query

Executes SQL query

When I execute `$query` query against CosmosDB container `$containerKey` and save result to $scopes variable `$variableName`

$query - The query to execute
$containerKey - The key of the container
$scopes - The comma-separated set of the variables scopes.
$variableName - The variable name to store results in JSON format.

Example 4. Execute query

When I execute `SELECT * FROM Items` query against CosmosDB container `test` and save result to scenario variable `result`
Then JSON element from `${result}` by JSON path `$` is equal to `
[
    {
        "id": "1",
        "category": "personal",
        "name": "groceries",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    },
    {
        "id": "2",
        "category": "private",
        "name": "stores",
        "description": "Pick up apples and strawberries.",
        "isComplete": false
    },
    {
        "id": "3",
        "category": "personal",
        "name": "work",
        "description": "Work till sundown",
        "isComplete": false
    }
]`IGNORING_EXTRA_FIELDS

Upsert

Upsert an item in the container

When I upsert `$data` into CosmosDB container `$containerKey`

$data - The data to update
$containerKey - The key of the container

Example 5. Upsert item

When I upsert `
{
    "id": "3",
    "category": "personal",
    "name": "work",
    "description": "Work till sundown",
    "isComplete": false
}` into CosmosDB container `test`

Insert

Insert an item in the container

When I insert `$data` into CosmosDB container `$containerKey`

$data - The data to update/insert
$containerKey - The key of the container

Example 6. Insert item

When I insert `
{
    "id": "3",
    "category": "personal",
    "name": "work",
    "description": "Vacation",
    "isComplete": false
}` into CosmosDB container `test`

Delete

Delete an item in the container

When I delete `$data` from CosmosDB container `$containerKey`

$data - The data to delete
$containerKey - The key of the container

Example 7. Delete item

When I delete `
{
    "id": "3",
    "category": "personal"
}` from CosmosDB container `test`