빠른 시작: NoSQL 데이터 API 작성기 사용

이 빠른 시작에서는 DAB(Data API Builder)를 사용하여 로컬 Azure Cosmos DB for NoSQL 에뮬레이터에 대한 GraphQL 엔드포인트를 만듭니다.

메모

Data API Builder의 NoSQL용 Azure Cosmos DB는 GraphQL 엔드포인트만 지원합니다. REST 엔드포인트는 이 데이터베이스 유형에 사용할 수 없습니다.

사전 요구 사항

Data API Builder CLI 설치

NuGet에서 Microsoft.DataApiBuilder 패키지를 .NET 도구로 설치합니다.

최신 버전 dotnet tool install을 Microsoft.DataApiBuilder 인수를 사용하여 설치하려면 --global을 사용하십시오.
```
dotnet tool install --global Microsoft.DataApiBuilder
```
메모

패키지가 이미 설치된 경우에는 dotnet tool update을 사용하여 대신 패키지를 업데이트하십시오.
```
dotnet tool update --global Microsoft.DataApiBuilder
```
dotnet tool list 인수를 사용하여 도구가 --global 설치되어 있는지 확인합니다.
```
dotnet tool list --global
```

에뮬레이터 이미지 끌어오기

NoSQL용 Azure Cosmos DB 에뮬레이터 이미지를 다운로드합니다. 에뮬레이터 이미지가 크므로 이 다운로드에는 몇 분 정도 걸릴 수 있습니다.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

에뮬레이터 시작

Docker에서 Cosmos DB 에뮬레이터를 실행합니다. AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE 설정은 에뮬레이터가 네트워크 엔드포인트를 알리게 하여, 호스트 컴퓨터에서 접근할 수 있도록 필요합니다 127.0.0.1.

docker run --name dab-cosmos --publish 8081:8081 --publish 10250-10255:10250-10255 --env AZURE_COSMOS_EMULATOR_IP_ADDRESS_OVERRIDE=127.0.0.1 --detach mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:latest

메모

에뮬레이터는 11개의 내부 파티션을 시작하고 준비하는 데 30~60초 가 걸릴 수 있습니다. 브라우저에서 열어 https://localhost:8081/_explorer/index.html 실행 중인지 확인할 수 있습니다. 브라우저에서 자체 서명된 인증서에 대해 경고할 수 있습니다. 계속 진행해도 안전합니다.

에뮬레이터 인증서 설치

Cosmos DB 에뮬레이터는 자체 서명된 SSL 인증서를 사용합니다. 데이터 API 작성기가 에뮬레이터에 연결할 수 있도록 이 인증서를 다운로드하고 신뢰합니다.

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
sudo cp ~/emulatorcert.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

curl -k https://localhost:8081/_explorer/emulator.pem > ~/emulatorcert.crt
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ~/emulatorcert.crt

curl.exe -k https://localhost:8081/_explorer/emulator.pem -o "$env:USERPROFILE\emulatorcert.crt"
Import-Certificate -CertStoreLocation "Cert:\CurrentUser\Root" -FilePath "$env:USERPROFILE\emulatorcert.crt"

메모

Windows는 인증서를 신뢰할지 여부를 묻는 보안 대화 상자를 표시합니다. 계속하려면 예를 선택합니다.

데이터베이스 및 시드 데이터 만들기

에뮬레이터의 기본 제공 데이터 탐색기를 사용하여 데이터베이스, 컨테이너 및 샘플 항목을 만듭니다. 추가 도구가 필요하지 않습니다. 데이터 탐색기는 에뮬레이터의 일부로 브라우저에서 실행됩니다.

에서 https://localhost:8081/_explorer/index.html데이터 탐색기를 엽니다.
새 데이터베이스를 선택합니다. todos를 데이터베이스 ID로 입력하고 확인을 선택합니다.
todos 데이터베이스를 확장하고 줄임표(...) 메뉴를 선택한 다음 새 컨테이너를 선택합니다. todos를 컨테이너 ID로 입력하고 /id를 파티션 키로 입력한 다음 확인을 선택합니다.
todos 컨테이너를 확장하고 항목을 선택합니다. 그런 다음 새 항목을 선택하고 기본 JSON을 다음 콘텐츠로 바꾸고 저장을 선택합니다. 각 항목에 대해 반복합니다.

항목 1:
```
{
  "id": "1",
  "title": "Walk the dog",
  "completed": false
}
```
항목 2:
```
{
  "id": "2",
  "title": "Feed the fish",
  "completed": false
}
```
항목 3:
```
{
  "id": "3",
  "title": "Comb the cat",
  "completed": true
}
```

GraphQL 스키마 파일 만들기

NoSQL용 Azure Cosmos DB에는 GraphQL 스키마 파일이 필요합니다. 다음 내용으로 명명된 schema.gql 파일을 만듭니다.

type Todo @model {
  id: ID!
  title: String!
  completed: Boolean!
}

데이터 API 작성기 구성

에뮬레이터의 기본 연결 문자열을 사용하여 구성을 초기화합니다.

dab init --database-type "cosmosdb_nosql" --host-mode "Development" --cosmosdb_nosql-database todos --graphql-schema schema.gql --connection-string "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="

Todo 엔터티를 추가합니다.

dab add Todo --source "todos" --permissions "anonymous:*"

dab-config.json 이제 파일은 다음 예제와 유사하게 표시됩니다.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "cosmosdb_nosql",
    "connection-string": "AccountEndpoint=https://localhost:8081/;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==",
    "options": {
      "database": "todos",
      "schema": "schema.gql"
    }
  },
  "runtime": {
    "graphql": {
      "enabled": true
    },
    "host": {
      "mode": "development"
    }
  },
  "entities": {
    "Todo": {
      "source": {
        "object": "todos",
        "type": "table"
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            "*"
          ]
        }
      ]
    }
  }
}

팁 (조언)

명령 dab init 및 dab add을 건너뛰고 여기에 표시된 콘텐츠로 dab-config.json 및 schema.gql 파일을 직접 생성할 수 있습니다.

API 시작

dab start를 사용하여 도구를 실행하고 엔터티에 대한 API 엔드포인트를 만드십시오.

dab start

출력에는 실행 중인 API의 주소가 포함되어야 합니다.

      Successfully completed runtime initialization.
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: <http://localhost:5000>

팁 (조언)

이 예제에서 애플리케이션은 포트 localhost에서 실행됩니다. 실행 중인 애플리케이션의 주소와 포트가 다를 수 있습니다.

API 테스트

브라우저를 열고 GraphQL 엔드포인트로 이동합니다.
```
http://localhost:5000/graphql
```
개발 모드에서 이 URL은 Nitro GraphQL IDE를 엽니다.
새 문서를 만들고 다음 쿼리를 실행하여 모든 할 일 항목을 검색합니다.
```
query {
  todos {
    items {
      id
      title
      completed
    }
  }
}
```

응답에는 세 가지 할 일 항목이 모두 포함되어야 합니다.

{
  "data": {
    "todos": {
      "items": [
        { "id": "1", "title": "Walk the dog", "completed": false },
        { "id": "2", "title": "Feed the fish", "completed": false },
        { "id": "3", "title": "Comb the cat", "completed": true }
      ]
    }
  }
}

정리

완료되면 Docker 컨테이너를 중지하고 제거합니다.

docker stop dab-cosmos && docker rm dab-cosmos

다음 단계:

GraphQL 엔드포인트

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-01