Azure DocumentDB용 데이터 API(미리 보기)

Azure DocumentDB용 데이터 API는 개발자가 데이터베이스 드라이버 없이도 데이터에 액세스하고 상호 작용할 수 있는 https 인터페이스입니다. HTTP 요청을 통해 제어 평면 및 집계 작업을 사용하도록 설정하여 데이터 작업을 간소화합니다. 이 API는 데이터베이스에 안전하고 확장 가능한 액세스를 제공하는 웹 애플리케이션에 적합합니다.

Azure DocumentDB에서 데이터 API 사용

Azure Portal, Azure CLI 또는 ARM 템플릿을 사용하여 이 기능을 사용하거나 사용하지 않도록 설정할 수 있습니다.

Azure Portal에서 Data API를 사용하도록 설정하는 단계

  1. Azure Portal로 이동

    • portal.azure.com

  2. Azure DocumentDB 클러스터로 이동

  3. '기능' 블레이드 열기

  4. '데이터 API'를 클릭합니다.

  5. '활성화'를 클릭합니다.

  6. 결과 확인

    • 이제 '기능' 블레이드에 'Data API'가 'On'으로 표시됩니다.

ARM 템플릿을 통해 클러스터에서 Data API를 사용하도록 설정하는 단계

  1. 연결 문자열 가져오기:

    • Azure Portal에서 클러스터의 연결 문자열을 가져옵니다.

  2. 인증 토큰 검색:

    • Windows PowerShell에서 다음 명령을 실행합니다. 
      az login
az account get-access-token --resource-type arm

  3. PATCH 요청 보내기:

    • Azure Portal에서 연결 문자열을 사용하고 다음을 사용하여 PATCH 요청을 보냅니다.
      • 인증 토큰: PowerShell에서 검색된 토큰을 사용합니다.
      • 본문: 
        {
  "properties": {
    "dataApi": {
      "mode": "Enabled"
    }
  }
}

  4. 결과 확인:

    • 응답 페이로드에 "dataApi": {"mode": "Enabled"}가 포함되어 있는지 확인합니다.
    • "데이터 API는 이 클러스터에서 지원되지 않습니다."라는 오류가 발생하는 경우 새로 프로비전된 클러스터만 Data API를 지원합니다.

클러스터 구성 업데이트

요청

메서드:PATCH
끝점:https://eastus2euap.management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.DocumentDB/mongoClusters/<ClusterName>?api-version=2024-10-01-preview

요청 본문

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

연결 문자열 가져오기

클러스터에 대한 연결 문자열을 가져오려면 다음 단계를 수행합니다.

  1. 만든 클러스터 로 이동합니다.
  2. 설정으로 이동하여 연결 문자열을 선택합니다.
  3. 제공된 데이터 API 엔드포인트 를 복사합니다.

데이터 API를 사용하는 방법

지원되는 작업, 데이터 API를 사용하는 방법을 살펴보겠습니다.

Aggregate

이 명령을 사용하여 컬렉션에 대한 집계 작업을 수행합니다.

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" ] } ] }

데이터베이스 목록 표시

지정된 클러스터의 모든 데이터베이스를 나열합니다.

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" } }

컬렉션 나열

특정 데이터베이스 내의 모든 컬렉션을 나열합니다.

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" } } } } ] }

스키마 가져오기

특정 데이터베이스의 스키마 세부 정보를 검색합니다.

.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" } }

제한점

  • 데이터 API는 새로 만든 클러스터에서 작동합니다.
  • 데이터 API는 재사용 가능한 액세스 토큰을 사용하는 액세스를 지원하지 않습니다.
  • 데이터 평면 집계 및 제한된 컨트롤 플레인 작업만 지원합니다.
  • Last updated on