API de dados para o Azure DocumentDB (versão prévia)

A API de Dados do Azure DocumentDB é uma interface https que permite que os desenvolvedores acessem e interajam com seus dados sem precisar de um driver de banco de dados. Ele simplifica as operações de dados habilitando operações de agregação e plano de controle por meio de solicitações HTTP. Essa API é ideal para aplicativos Web, fornecendo acesso seguro e escalonável aos bancos de dados.

Habilitando a API de Dados no Azure DocumentDB

Você pode habilitar ou desabilitar esse recurso usando o portal do Azure, a CLI do Azure ou um modelo do ARM.

Etapas para habilitar a API de Dados no portal do Azure

  1. Ir para o portal do Azure

    • portal.azure.com

  2. Vá para o cluster do Azure DocumentDB

  3. Abrir o painel 'Recursos'

  4. Clique em 'API de Dados'

  5. Clique em 'Habilitar'

  6. Verificar o resultado

    • Sua folha 'Recursos' agora deve exibir 'API de Dados' como 'Ativado'.

Etapas para habilitar a API de Dados no cluster por meio do modelo do ARM

  1. Obter string de conexão

    • Obtenha a cadeia de conexão do cluster no portal do Azure.

  2. Recuperar token de autenticação:

    • Execute os seguintes comandos no Windows PowerShell: 
      az login
az account get-access-token --resource-type arm

  3. Enviar solicitação PATCH:

    • Use a cadeia de conexão do portal do Azure e envie uma solicitação PATCH com:
      • Token de autenticação: use o token recuperado do PowerShell.
      • Corpo: 
        {
  "properties": {
    "dataApi": {
      "mode": "Enabled"
    }
  }
}

  4. Verificar o resultado:

    • Verifique se o conteúdo da resposta inclui "dataApi": {"mode": "Enabled"}.
    • Se você encontrar o erro "A API de dados não tem suporte neste cluster", observe que apenas clusters provisionados recentemente dão suporte à API de Dados.

Atualizar a configuração do cluster

Solicitação

Método:PATCH
Ponto de extremidade:https://eastus2euap.management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.DocumentDB/mongoClusters/<ClusterName>?api-version=2024-10-01-preview

Corpo da solicitação

{
  "properties": {
    "dataApi": {
      "mode": "Enabled"
    }
  }
}

Obter cadeia de conexão

Para obter a cadeia de conexão do cluster, siga estas etapas:

  1. Navegue até o cluster que você criou.
  2. Vá para Configurações e selecione Cadeias de Conexão.
  3. Copie o endpoint da API de Dados fornecido.

Como usar a API de Dados

Vamos explorar as operações com suporte, como usar a API de Dados.

Aggregate

Use este comando para executar uma operação de agregação em uma coleção.

curl {cluster-name}.data.mongocluster.cosmos.azure.com:443/data/v1/action/aggregate -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database" : "testDB", "collection" : "testCollection", "pipeline" : [{"$limit" : 500}]}' --user "{username}:{password}"

{ "documents" : [ { "_id" : { "$oid" : "680957492551581200c73bf8" }, "name" : "Sample Document", "createdAt" : { "$date" : { "$numberLong" : "1745442633506" } }, "tags" : [ "test", "mongo", "sample" ] } ] }

Listar bancos de dados

Liste todos os bancos de dados no cluster especificado.

curl {cluster-name}.data.global.mongocluster.cosmos.azure.com:443/data/v1/action/listDatabases -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{}' --user "{username}:{password}"

{ "databases" : [ { "name" : "testDB", "sizeOnDisk" : { "$numberInt" : "0" }, "empty" : false }, { "name" : "test", "sizeOnDisk" : { "$numberInt" : "0" }, "empty" : false } ], "totalSize" : { "$numberInt" : "0" }, "ok" : { "$numberDouble" : "1.0" } }

Listar coleções

Liste todas as coleções em um banco de dados específico.

curl {cluster-name}.data.global.mongocluster.cosmos.azure.com:443/data/v1/action/listCollections -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database": "newDB"}' --user "{username}:{password}"

{ "collections" : [ { "name" : "testCollection", "type" : "collection", "options" : {  }, "info" : { "readOnly" : false, "uuid" : { "$binary" : { "base64" : "mNh96KepTm+NtLtALGxDiw==", "subType" : "04" } } }, "idIndex" : { "v" : { "$numberInt" : "2" }, "name" : "_id_", "key" : { "_id" : { "$numberInt" : "1" } } } } ] }

Obter esquema

Recupere os detalhes do esquema de um banco de dados específico.

Esta é a versão formatada para o arquivo .md:

curl {cluster-name}.data.mongocluster.cosmos.azure.com:443/data/v1/action/getSchema -H "Content-Type: application/ejson" -H "Accept:application/ejson" -d '{"database" : "testDB", "collection" : "testCollection"}' --user "{username}:{password}"

{ "_id" : { "bsonType" : "objectId" }, "name" : { "bsonType" : "string" }, "createdAt" : { "bsonType" : "date" }, "tags" : { "bsonType" : "array" } }

Limitações

  • A API de dados funciona no cluster recém-criado.
  • A API de dados não dá suporte ao acesso usando o token de acesso reutilizável.
  • Só dá suporte à agregação do plano de dados e a ações limitadas do plano de controle.
  • Last updated on