--- title: Azure Cosmos DB actions source: https://docs.newrelic.com/docs/workflow-automation/setup-and-configure/actions-catalog/azure/azure-cosmos-db --- The Azure Cosmos DB actions let you read, write, and manage documents and databases in Azure Cosmos DB directly from your workflows. All actions authenticate using an Azure AD service principal and communicate with the Cosmos DB data plane. ## Get an item [#azure-cosmos-getitem] This action reads a single document by ID from an Azure Cosmos DB container using the [Azure Cosmos DB - Get Document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-a-document) REST API. ### Inputs | Input | Type | Description | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | String | **Required.** Azure AD app (client) ID. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `clientSecret` | String | **Required.** Azure AD client secret. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `tenantId` | String | **Required.** The Azure AD tenant identifier. Can be passed as a secret. | | `accountName` | String | **Required.** The Cosmos DB account name. For example, `"my-cosmos-account"`. | | `databaseId` | String | **Required.** The database identifier. For example, `"TestDb"`. | | `collectionId` | String | **Required.** The container (collection) identifier. For example, `"Items"`. | | `itemId` | String | **Required.** The document `id` to read. For example, `"121"`. | | `partitionKey` | String | **Required.** The partition key value for the document. For example, `"beta"`. | | `selectors` | List | **Optional.** A list of selectors used to extract specific values from the response. For example, `[{"name": "item", "expression": ".response"}]`. | ### Outputs | Output | Type | Description | | --------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `success` | Boolean | `true` on success, `false` on error or document not found. | | `errorMessage` | String | Failure reason as a message. | | `response` | Object | The document body. For more information, see the [Azure Cosmos DB - Get Document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-a-document) REST API. | | `eTag` | String | The ETag of the returned document, used for optimistic concurrency control. | | `requestCharge` | String | The request units (RU) consumed by the operation. | ### Example ```yaml name: cosmosGetItemWorkflow description: '' steps: - name: get_item type: action action: azure.cosmos.getItem version: 1 inputs: clientId: ${{ :secrets:azure-client-id }} clientSecret: ${{ :secrets:azure-client-secret }} tenantId: ${{ :secrets:azure-client-tenant }} accountName: my-cosmos-account databaseId: TestDb collectionId: Items itemId: "121" partitionKey: beta selectors: - name: item expression: ".response" next: log_result - name: log_result type: action action: newrelic.ingest.sendLogs version: 1 inputs: logs: - message: 'azure.cosmos.getItem result: ${{ .steps.get_item.outputs | tostring }}' next: end ``` ## Create an item [#azure-cosmos-createitem] This action creates a new document in an Azure Cosmos DB container using the [Azure Cosmos DB - Create Document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/create-a-document) REST API. ### Inputs | Input | Type | Description | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | String | **Required.** Azure AD app (client) ID. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `clientSecret` | String | **Required.** Azure AD client secret. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `tenantId` | String | **Required.** The Azure AD tenant identifier. Can be passed as a secret. | | `accountName` | String | **Required.** The Cosmos DB account name. For example, `"my-cosmos-account"`. | | `databaseId` | String | **Required.** The database identifier. For example, `"TestDb"`. | | `collectionId` | String | **Required.** The container (collection) identifier. For example, `"Items"`. | | `partitionKey` | String | **Required.** The partition key value for the new document. Must match the document's partition key property value. For example, `"beta"`. | | `item` | Map | **Required.** The document to create. Must include the partition key property (for example, `pk`) set to the same value as `partitionKey`, and typically an `id`. | | `selectors` | List | **Optional.** A list of selectors used to extract specific values from the response. For example, `[{"name": "newId", "expression": ".response.id"}]`. | ### Outputs | Output | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `success` | Boolean | `true` on 201 Created, `false` on error. | | `errorMessage` | String | Failure reason as a message. | | `response` | Object | The created document as stored, including system fields. For more information, see the [Azure Cosmos DB - Create Document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/create-a-document) REST API. | | `eTag` | String | The ETag of the created document, used for optimistic concurrency control. | | `requestCharge` | String | The request units (RU) consumed by the operation. | ### Example ```yaml name: cosmosCreateItemWorkflow description: '' steps: - name: create_item type: action action: azure.cosmos.createItem version: 1 inputs: clientId: ${{ :secrets:azure-client-id }} clientSecret: ${{ :secrets:azure-client-secret }} tenantId: ${{ :secrets:azure-client-tenant }} accountName: my-cosmos-account databaseId: TestDb collectionId: Items partitionKey: beta item: id: "423" pk: beta name: created-by-workflow category: demo value: 42 selectors: - name: newId expression: .response.id next: log_result - name: log_result type: action action: newrelic.ingest.sendLogs version: 1 inputs: logs: - message: 'azure.cosmos.createItem succeeded=${{ .steps.create_item.outputs.success }} newId=${{ .steps.create_item.outputs.newId }}' next: end ``` ## Update an item [#azure-cosmos-updateitem] This action replaces or upserts a document in an Azure Cosmos DB container using the [Azure Cosmos DB - Replace Document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/replace-a-document) REST API. By default (`upsert: false`) the document must already exist. Set `upsert: true` to create the document if it does not exist. ### Inputs | Input | Type | Description | | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | String | **Required.** Azure AD app (client) ID. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `clientSecret` | String | **Required.** Azure AD client secret. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `tenantId` | String | **Required.** The Azure AD tenant identifier. Can be passed as a secret. | | `accountName` | String | **Required.** The Cosmos DB account name. For example, `"my-cosmos-account"`. | | `databaseId` | String | **Required.** The database identifier. For example, `"TestDb"`. | | `collectionId` | String | **Required.** The container (collection) identifier. For example, `"Items"`. | | `itemId` | String | **Required.** The document `id` to replace. For example, `"323"`. | | `partitionKey` | String | **Required.** The partition key value for the document. For example, `"beta"`. | | `item` | Map | **Required.** The full replacement document. Must include the same `id` and partition key value as the existing document. | | `upsert` | Boolean | **Optional.** When `false` (default), replaces the document and returns an error if it does not exist. When `true`, creates the document if it does not exist. Accepts `true` or `false`. | | `selectors` | List | **Optional.** A list of selectors used to extract specific values from the response. For example, `[{"name": "updatedId", "expression": ".response.id"}]`. | ### Outputs | Output | Type | Description | | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `success` | Boolean | `true` on success, `false` on error. | | `errorMessage` | String | Failure reason as a message. | | `response` | Object | The stored document after the write. For more information, see the [Azure Cosmos DB - Replace Document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/replace-a-document) REST API. | | `eTag` | String | The ETag of the stored document after the write, used for optimistic concurrency control. | | `requestCharge` | String | The request units (RU) consumed by the operation. | ### Example ```yaml name: cosmosUpdateItemWorkflow description: '' steps: - name: update_item type: action action: azure.cosmos.updateItem version: 1 inputs: clientId: ${{ :secrets:azure-client-id }} clientSecret: ${{ :secrets:azure-client-secret }} tenantId: ${{ :secrets:azure-client-tenant }} accountName: my-cosmos-account databaseId: TestDb collectionId: Items itemId: "323" partitionKey: beta upsert: false item: id: "323" pk: beta name: updated-by-workflow category: demo value: 43 selectors: - name: updatedId expression: .response.id - name: eTag expression: .response._etag next: log_result - name: log_result type: action action: newrelic.ingest.sendLogs version: 1 inputs: logs: - message: 'azure.cosmos.updateItem succeeded=${{ .steps.update_item.outputs.success }} updatedId=${{ .steps.update_item.outputs.updatedId }} eTag=${{ .steps.update_item.outputs.eTag }}' next: end ``` ## Delete an item [#azure-cosmos-deleteitem] This action deletes a document from an Azure Cosmos DB container using the [Azure Cosmos DB - Delete Document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/delete-a-document) REST API. ### Inputs | Input | Type | Description | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | String | **Required.** Azure AD app (client) ID. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `clientSecret` | String | **Required.** Azure AD client secret. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `tenantId` | String | **Required.** The Azure AD tenant identifier. Can be passed as a secret. | | `accountName` | String | **Required.** The Cosmos DB account name. For example, `"my-cosmos-account"`. | | `databaseId` | String | **Required.** The database identifier. For example, `"TestDb"`. | | `collectionId` | String | **Required.** The container (collection) identifier. For example, `"Items"`. | | `itemId` | String | **Required.** The document `id` to delete. For example, `"121"`. | | `partitionKey` | String | **Required.** The partition key value for the document. Must match the document's partition key property value. For example, `"beta"`. | | `selectors` | List | **Optional.** A list of selectors used to extract specific values from the response. For example, `[{"name": "statusCode", "expression": ".response.status_code"}]`. | ### Outputs | Output | Type | Description | | --------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `success` | Boolean | `true` on 204 No Content, `false` on error. | | `errorMessage` | String | Failure reason as a message. | | `response` | Object | The delete response. Typically empty on success. Use a selector such as `.response.status_code` to confirm the status. For more information, see the [Azure Cosmos DB - Delete Document](https://learn.microsoft.com/en-us/rest/api/cosmos-db/delete-a-document) REST API. | | `requestCharge` | String | The request units (RU) consumed by the operation. | ### Example ```yaml name: cosmosDeleteItemWorkflow description: '' steps: - name: delete_item type: action action: azure.cosmos.deleteItem version: 1 inputs: clientId: ${{ :secrets:azure-client-id }} clientSecret: ${{ :secrets:azure-client-secret }} tenantId: ${{ :secrets:azure-client-tenant }} accountName: my-cosmos-account databaseId: TestDb collectionId: Items itemId: "121" partitionKey: beta selectors: - name: statusCode expression: ".response.status_code" next: log_result - name: log_result type: action action: newrelic.ingest.sendLogs version: 1 inputs: logs: - message: 'azure.cosmos.deleteItem result: ${{ .steps.delete_item.outputs | tostring }}' next: end ``` ## Describe a database [#azure-cosmos-describedatabase] This action retrieves metadata for an Azure Cosmos DB database using the [Azure Cosmos DB - Get Database](https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-a-database) REST API. ### Inputs | Input | Type | Description | | -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `clientId` | String | **Required.** Azure AD app (client) ID. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `clientSecret` | String | **Required.** Azure AD client secret. Must be passed as a secret. See how to [register an Azure app](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/api/register-app-for-token). | | `tenantId` | String | **Required.** The Azure AD tenant identifier. Can be passed as a secret. | | `accountName` | String | **Required.** The Cosmos DB account name. For example, `"my-cosmos-account"`. | | `databaseId` | String | **Required.** The database to describe. For example, `"TestDb"`. | | `selectors` | List | **Optional.** A list of selectors used to extract specific values from the response. For example, `[{"name": "id", "expression": ".response.id"}]`. | ### Outputs | Output | Type | Description | | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `success` | Boolean | `true` on success, `false` on error or database not found. | | `errorMessage` | String | Failure reason as a message. | | `response` | Object | The database resource, including fields such as `id`, `_rid`, `_self`, `_ts`, `_colls`, and `_users`. For more information, see the [Azure Cosmos DB - Get Database](https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-a-database) REST API. | | `eTag` | String | The ETag of the database resource. | ### Example ```yaml name: cosmosDescribeDatabaseWorkflow description: '' steps: - name: describeDatabase type: action action: azure.cosmos.describeDatabase version: 1 inputs: clientId: ${{ :secrets:azure-client-id }} clientSecret: ${{ :secrets:azure-client-secret }} tenantId: ${{ :secrets:azure-client-tenant }} accountName: my-cosmos-account databaseId: TestDb selectors: - name: database expression: ".response" - name: id expression: ".response.id" - name: eTag expression: ".eTag" - name: logResult type: action action: newrelic.ingest.sendLogs version: 1 inputs: logs: - message: 'azure.cosmos.describeDatabase database: ${{ .steps.describeDatabase.outputs.database | tostring }}' attributes: success: ${{ .steps.describeDatabase.outputs.success }} id: ${{ .steps.describeDatabase.outputs.id }} eTag: ${{ .steps.describeDatabase.outputs.eTag }} next: end ```