Sql Resources - Create Update Client Encryption Key

Servicio:

Cosmos DB Resource Provider

Versión de la API:

2025-04-15

Cree o actualice clientEncryptionKey. Esta API está pensada para invocarse a través de herramientas como Azure PowerShell (en lugar de directamente).

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{accountName}/sqlDatabases/{databaseName}/clientEncryptionKeys/{clientEncryptionKeyName}?api-version=2025-04-15

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
accountName	path	True	string minLength: 3 maxLength: 50 pattern: ^[a-z0-9]+(-[a-z0-9]+)*	Nombre de la cuenta de base de datos de Cosmos DB.
clientEncryptionKeyName	path	True	string	Nombre clientEncryptionKey de Cosmos DB.
databaseName	path	True	string	Nombre de la base de datos de Cosmos DB.
resourceGroupName	path	True	string minLength: 1 maxLength: 90	Nombre del grupo de recursos. El nombre distingue mayúsculas de minúsculas.
subscriptionId	path	True	string minLength: 1	Identificador de la suscripción de destino.
api-version	query	True	string minLength: 1	Versión de API que se usará para la operación.

Cuerpo de la solicitud

Nombre	Tipo	Description
createUpdateClientEncryptionKeyParameters	ClientEncryptionKeyCreateUpdateParameters	Parámetros que se van a proporcionar para la clave de cifrado de cliente.

Respuestas

Nombre	Tipo	Description
200 OK	ClientEncryptionKeyGetResults	La operación de creación o actualización de la clave de cifrado de cliente se completó correctamente.
202 Accepted		La operación de creación o actualización de la clave de cifrado de cliente se completará de forma asincrónica. Encabezados azure-AsyncOperation: string location: string

Seguridad

azure_auth

Flujo de OAuth2 de Azure Active Directory

Tipo: oauth2
Flujo: implicit
Dirección URL de autorización: https://login.microsoftonline.com/common/oauth2/authorize

Ámbitos

Nombre	Description
user_impersonation	Suplantar tu cuenta de usuario

Ejemplos

CosmosDBClientEncryptionKeyCreateUpdate

Solicitud de ejemplo

HTTP

PUT https://management.azure.com/subscriptions/subId/resourceGroups/rgName/providers/Microsoft.DocumentDB/databaseAccounts/accountName/sqlDatabases/databaseName/clientEncryptionKeys/cekName?api-version=2025-04-15

{
  "properties": {
    "resource": {
      "id": "cekName",
      "encryptionAlgorithm": "AEAD_AES_256_CBC_HMAC_SHA256",
      "wrappedDataEncryptionKey": "U3dhZ2dlciByb2Nrcw==",
      "keyWrapMetadata": {
        "name": "customerManagedKey",
        "type": "AzureKeyVault",
        "value": "AzureKeyVault Key URL",
        "algorithm": "RSA-OAEP"
      }
    }
  }
}

Java

import com.azure.resourcemanager.cosmos.models.ClientEncryptionKeyCreateUpdateParameters;
import com.azure.resourcemanager.cosmos.models.ClientEncryptionKeyResource;
import com.azure.resourcemanager.cosmos.models.KeyWrapMetadata;

/**
 * Samples for SqlResources CreateUpdateClientEncryptionKey.
 */
public final class Main {
    /*
     * x-ms-original-file: specification/cosmos-db/resource-manager/Microsoft.DocumentDB/stable/2025-04-15/examples/
     * CosmosDBSqlClientEncryptionKeyCreateUpdate.json
     */
    /**
     * Sample code: CosmosDBClientEncryptionKeyCreateUpdate.
     * 
     * @param azure The entry point for accessing resource management APIs in Azure.
     */
    public static void cosmosDBClientEncryptionKeyCreateUpdate(com.azure.resourcemanager.AzureResourceManager azure) {
        azure.cosmosDBAccounts().manager().serviceClient().getSqlResources()
            .createUpdateClientEncryptionKey("rgName", "accountName", "databaseName", "cekName",
                new ClientEncryptionKeyCreateUpdateParameters().withResource(new ClientEncryptionKeyResource()
                    .withId("cekName").withEncryptionAlgorithm("AEAD_AES_256_CBC_HMAC_SHA256")
                    .withWrappedDataEncryptionKey("U3dhZ2dlciByb2Nrcw==".getBytes())
                    .withKeyWrapMetadata(new KeyWrapMetadata().withName("customerManagedKey").withType("AzureKeyVault")
                        .withValue("AzureKeyVault Key URL").withAlgorithm("RSA-OAEP"))),
                com.azure.core.util.Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Python

from azure.identity import DefaultAzureCredential

from azure.mgmt.cosmosdb import CosmosDBManagementClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-cosmosdb
# USAGE
    python cosmos_db_sql_client_encryption_key_create_update.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = CosmosDBManagementClient(
        credential=DefaultAzureCredential(),
        subscription_id="subId",
    )

    response = client.sql_resources.begin_create_update_client_encryption_key(
        resource_group_name="rgName",
        account_name="accountName",
        database_name="databaseName",
        client_encryption_key_name="cekName",
        create_update_client_encryption_key_parameters={
            "properties": {
                "resource": {
                    "encryptionAlgorithm": "AEAD_AES_256_CBC_HMAC_SHA256",
                    "id": "cekName",
                    "keyWrapMetadata": {
                        "algorithm": "RSA-OAEP",
                        "name": "customerManagedKey",
                        "type": "AzureKeyVault",
                        "value": "AzureKeyVault Key URL",
                    },
                    "wrappedDataEncryptionKey": "U3dhZ2dlciByb2Nrcw==",
                }
            }
        },
    ).result()
    print(response)


# x-ms-original-file: specification/cosmos-db/resource-manager/Microsoft.DocumentDB/stable/2025-04-15/examples/CosmosDBSqlClientEncryptionKeyCreateUpdate.json
if __name__ == "__main__":
    main()

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Go

package armcosmos_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/cosmos/armcosmos/v3"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/011ecc5633300a5eefe43dde748f269d39e96458/specification/cosmos-db/resource-manager/Microsoft.DocumentDB/stable/2025-04-15/examples/CosmosDBSqlClientEncryptionKeyCreateUpdate.json
func ExampleSQLResourcesClient_BeginCreateUpdateClientEncryptionKey() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armcosmos.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	poller, err := clientFactory.NewSQLResourcesClient().BeginCreateUpdateClientEncryptionKey(ctx, "rgName", "accountName", "databaseName", "cekName", armcosmos.ClientEncryptionKeyCreateUpdateParameters{
		Properties: &armcosmos.ClientEncryptionKeyCreateUpdateProperties{
			Resource: &armcosmos.ClientEncryptionKeyResource{
				EncryptionAlgorithm: to.Ptr("AEAD_AES_256_CBC_HMAC_SHA256"),
				ID:                  to.Ptr("cekName"),
				KeyWrapMetadata: &armcosmos.KeyWrapMetadata{
					Name:      to.Ptr("customerManagedKey"),
					Type:      to.Ptr("AzureKeyVault"),
					Algorithm: to.Ptr("RSA-OAEP"),
					Value:     to.Ptr("AzureKeyVault Key URL"),
				},
				WrappedDataEncryptionKey: []byte("U3dhZ2dlciByb2Nrcw=="),
			},
		},
	}, nil)
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	res, err := poller.PollUntilDone(ctx, nil)
	if err != nil {
		log.Fatalf("failed to pull the result: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.ClientEncryptionKeyGetResults = armcosmos.ClientEncryptionKeyGetResults{
	// 	Name: to.Ptr("cekName"),
	// 	Type: to.Ptr("Microsoft.DocumentDB/databaseAccounts/sqlDatabases/clientEncryptionKey"),
	// 	ID: to.Ptr("/subscriptions/subId/resourceGroups/rgName/providers/Microsoft.DocumentDB/databaseAccounts/accountName/sqlDatabases/databaseName/clientEncryptionKeys/cekName"),
	// 	Properties: &armcosmos.ClientEncryptionKeyGetProperties{
	// 		Resource: &armcosmos.ClientEncryptionKeyGetPropertiesResource{
	// 			EncryptionAlgorithm: to.Ptr("AEAD_AES_256_CBC_HMAC_SHA256"),
	// 			ID: to.Ptr("cekName"),
	// 			KeyWrapMetadata: &armcosmos.KeyWrapMetadata{
	// 				Name: to.Ptr("customerManagedKey"),
	// 				Type: to.Ptr("AzureKeyVault"),
	// 				Algorithm: to.Ptr("RSA-OAEP"),
	// 				Value: to.Ptr("AzureKeyVault Key URL"),
	// 			},
	// 			WrappedDataEncryptionKey: []byte("U3dhZ2dlciByb2Nrcw=="),
	// 			Etag: to.Ptr("00000000-0000-0000-7a1f-bc0828e801d7"),
	// 			Rid: to.Ptr("tNc4AAAAAAAQkjzWAgAAAA=="),
	// 			Ts: to.Ptr[float32](1626425552),
	// 		},
	// 	},
	// }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

JavaScript

const { CosmosDBManagementClient } = require("@azure/arm-cosmosdb");
const { DefaultAzureCredential } = require("@azure/identity");
require("dotenv/config");

/**
 * This sample demonstrates how to Create or update a ClientEncryptionKey. This API is meant to be invoked via tools such as the Azure Powershell (instead of directly).
 *
 * @summary Create or update a ClientEncryptionKey. This API is meant to be invoked via tools such as the Azure Powershell (instead of directly).
 * x-ms-original-file: specification/cosmos-db/resource-manager/Microsoft.DocumentDB/stable/2025-04-15/examples/CosmosDBSqlClientEncryptionKeyCreateUpdate.json
 */
async function cosmosDbClientEncryptionKeyCreateUpdate() {
  const subscriptionId = process.env["COSMOSDB_SUBSCRIPTION_ID"] || "subId";
  const resourceGroupName = process.env["COSMOSDB_RESOURCE_GROUP"] || "rgName";
  const accountName = "accountName";
  const databaseName = "databaseName";
  const clientEncryptionKeyName = "cekName";
  const createUpdateClientEncryptionKeyParameters = {
    resource: {
      encryptionAlgorithm: "AEAD_AES_256_CBC_HMAC_SHA256",
      id: "cekName",
      keyWrapMetadata: {
        name: "customerManagedKey",
        type: "AzureKeyVault",
        algorithm: "RSA-OAEP",
        value: "AzureKeyVault Key URL",
      },
      wrappedDataEncryptionKey: Buffer.from("U3dhZ2dlciByb2Nrcw=="),
    },
  };
  const credential = new DefaultAzureCredential();
  const client = new CosmosDBManagementClient(credential, subscriptionId);
  const result = await client.sqlResources.beginCreateUpdateClientEncryptionKeyAndWait(
    resourceGroupName,
    accountName,
    databaseName,
    clientEncryptionKeyName,
    createUpdateClientEncryptionKeyParameters,
  );
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Respuesta de muestra

status code:

200

{
  "id": "/subscriptions/subId/resourceGroups/rgName/providers/Microsoft.DocumentDB/databaseAccounts/accountName/sqlDatabases/databaseName/clientEncryptionKeys/cekName",
  "name": "cekName",
  "type": "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/clientEncryptionKey",
  "properties": {
    "resource": {
      "id": "cekName",
      "encryptionAlgorithm": "AEAD_AES_256_CBC_HMAC_SHA256",
      "wrappedDataEncryptionKey": "U3dhZ2dlciByb2Nrcw==",
      "keyWrapMetadata": {
        "name": "customerManagedKey",
        "type": "AzureKeyVault",
        "value": "AzureKeyVault Key URL",
        "algorithm": "RSA-OAEP"
      },
      "_rid": "tNc4AAAAAAAQkjzWAgAAAA==",
      "_ts": 1626425552,
      "_etag": "00000000-0000-0000-7a1f-bc0828e801d7"
    }
  }
}

status code:

202

Definiciones

Nombre	Description
ClientEncryptionKeyCreateUpdateParameters	Parámetros que se van a proporcionar para la clave de cifrado de cliente.
ClientEncryptionKeyGetResults	Clave de cifrado de cliente.
ClientEncryptionKeyResource	Objeto de recurso de clave de cifrado de cliente de Cosmos DB.
KeyWrapMetadata	Representa los metadatos de encapsulado de claves que un proveedor de ajuste de claves puede usar para encapsular o desencapsular una clave de cifrado de cliente.
Resource

ClientEncryptionKeyCreateUpdateParameters

Object

Parámetros que se van a proporcionar para la clave de cifrado de cliente.

Nombre	Tipo	Description
properties.resource	ClientEncryptionKeyResource	El formato JSON estándar de clientEncryptionKey

ClientEncryptionKeyGetResults

Object

Clave de cifrado de cliente.

Nombre	Tipo	Description
id	string	Identificador de recurso único de la cuenta de base de datos.
name	string	Nombre de la cuenta de base de datos.
properties.resource	Resource
type	string	Tipo de recurso de Azure.

ClientEncryptionKeyResource

Object

Objeto de recurso de clave de cifrado de cliente de Cosmos DB.

Nombre	Tipo	Description
encryptionAlgorithm	string	Algoritmo de cifrado que se usará junto con esta clave de cifrado de cliente para cifrar o descifrar datos.
id	string	Nombre de ClientEncryptionKey
keyWrapMetadata	KeyWrapMetadata	Metadatos del proveedor de ajuste que se puede usar para desencapsular la clave de cifrado de cliente ajustada.
wrappedDataEncryptionKey	string (byte)	Forma ajustada (cifrada) de la clave representada como una matriz de bytes.

KeyWrapMetadata

Object

Representa los metadatos de encapsulado de claves que un proveedor de ajuste de claves puede usar para encapsular o desencapsular una clave de cifrado de cliente.

Nombre	Tipo	Description
algorithm	string	Algoritmo usado en el ajuste y desencapsulado de la clave de cifrado de datos.
name	string	Nombre de KeyEncryptionKey asociado (también conocido como CustomerManagedKey).
type	string	ProviderName de KeyStoreProvider.
value	string	Referencia o vínculo a KeyEncryptionKey.

Resource

Object

Nombre	Tipo	Description
_etag	string	Propiedad generada por el sistema que representa la etag de recursos necesaria para el control de simultaneidad optimista.
_rid	string	Propiedad generada por el sistema. Identificador único.
_ts	number	Propiedad generada por el sistema que denota la última marca de tiempo actualizada del recurso.
encryptionAlgorithm	string	Algoritmo de cifrado que se usará junto con esta clave de cifrado de cliente para cifrar o descifrar datos.
id	string	Nombre de ClientEncryptionKey
keyWrapMetadata	KeyWrapMetadata	Metadatos del proveedor de ajuste que se puede usar para desencapsular la clave de cifrado de cliente ajustada.
wrappedDataEncryptionKey	string (byte)	Forma ajustada (cifrada) de la clave representada como una matriz de bytes.