빠른 시작: .NET용 Azure Cosmos DB for Apache Gremlin 라이브러리

아티클
02/29/2024

적용 대상: Gremlin

Azure Cosmos DB for Apache Gremlin는 Gremlin 쿼리 언어를 사용하는 그래프 컴퓨팅 프레임워크인 널리 사용되는 Apache Tinkerpop을 구현하는 완전 관리형 그래프 데이터베이스 서비스입니다. Gremlin용 API는 최소한의 관리로 필요한 만큼 스케일 아웃 및 스케일 아웃할 수 있는 서비스와 함께 Gremlin 사용을 시작할 수 있는 부담 없는 방법을 제공합니다.

이 빠른 시작에서는 Gremlin.Net 라이브러리를 사용하여 새로 만들어진 Azure Cosmos DB for Gremlin 계정에 연결합니다.

라이브러리 소스 코드 | 패키지(NuGet)

필수 조건

활성 구독이 있는 Azure 계정.
- Azure 구독이 없으신가요? 무료 Azure 계정을 등록합니다.
- Azure 구독을 원하지 않으시나요? 구독 없이 Azure Cosmos DB를 무료로 사용해 볼 수 있습니다.
.NET(LTS)
- .NET이 설치되어 있지 않나요? GitHub Codespaces에서 이 빠른 시작을 시도해 보세요.
Azure CLI(명령줄 인터페이스)

Azure Cloud Shell

Azure는 브라우저를 통해 사용할 수 있는 대화형 셸 환경인 Azure Cloud Shell을 호스트합니다. Cloud Shell에서 Bash 또는 PowerShell을 사용하여 Azure 서비스 작업을 수행할 수 있습니다. 로컬 환경에 아무 것도 설치할 필요 없이 Azure Cloud Shell의 미리 설치된 명령을 사용하여 이 문서의 코드를 실행할 수 있습니다.

Azure Cloud Shell을 시작하려면 다음을 수행합니다.

옵션	예제/링크
코드 또는 명령 블록의 오른쪽 상단에서 시도를 선택합니다. 시도를 선택해도 코드 또는 명령이 Cloud Shell에 자동으로 복사되지 않습니다.
https://shell.azure.com으로 이동하거나 Cloud Shell 시작 단추를 선택하여 브라우저에서 Cloud Shell을 엽니다.
Azure Portal의 오른쪽 위에 있는 메뉴 모음에서 Cloud Shell 단추를 선택합니다.

Azure Cloud Shell을 사용하려면:

Cloud Shell을 시작합니다.
코드 블록(또는 명령 블록)에서 복사 단추를 선택하여 코드 또는 명령을 복사합니다.
Windows 및 Linux에서 Ctrl+Shift+V를 선택하거나 macOS에서 Cmd+Shift+V를 선택하여 코드 또는 명령을 Cloud Shell 세션에 붙여넣습니다.
Enter를 선택하여 코드 또는 명령을 실행합니다.

설정

이 섹션에서는 API for Gremlin 계정을 만들고 라이브러리를 사용하여 계정에 연결하도록 .NET 프로젝트를 설정하는 과정을 안내합니다.

Gremlin용 API 계정 만들기

.NET 라이브러리를 사용하려면 먼저 API for Gremlin 계정을 만들어야 합니다. 또한 데이터베이스와 그래프를 내부에 두는 것도 도움이 됩니다.

accountName, resourceGroupName 및 location에 대한 셸 변수를 만듭니다.

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"
location="westus"

# Variable for account name with a randomly generated suffix

let suffix=$RANDOM*$RANDOM
accountName="msdocs-gremlin-$suffix"

아직 로그인하지 않았다면 az login을 사용하여 Azure CLI에 로그인합니다.
구독에 새 리소스 그룹을 만들려면 az group create를 사용합니다.
```
az group create \
    --name $resourceGroupName \
    --location $location
```
기본 설정으로 새 API for Gremlin 계정을 만들려면 az cosmosdb create를 사용합니다.
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
참고 항목

Azure 구독당 최대 1개의 체험 계층 Azure Cosmos DB 계정을 사용할 수 있으며 계정을 만들 때 옵트인해야 합니다. 이 명령이 무료 계층 할인을 적용하지 못하면 구독의 다른 계정이 이미 무료 계층으로 사용하도록 설정되었음을 의미합니다.

az cosmosdb show를 사용하여 계정의 Gremlin용 API 엔드포인트 NAME을 가져옵니다.

az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "name"

az-cosmosdb-keys-list를 사용하여 계정에 대한 키 목록에서 KEY를 찾습니다.

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

NAME 및 KEY 값을 기록합니다. 나중에 이 자격 증명을 사용합니다.

az cosmosdb gremlin database create를 사용하여 cosmicworks라는 데이터베이스를 만듭니다.

az cosmosdb gremlin database create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --name "cosmicworks"

az cosmosdb gremlin graph create를 사용하여 그래프를 만듭니다. 그래프 이름을 products로 지정한 다음, 처리량을 400으로 설정하고 마지막으로 파티션 키 경로를 /category로 설정합니다.

az cosmosdb gremlin graph create \
    --resource-group $resourceGroupName \
    --account-name $accountName \
    --database-name "cosmicworks" \
    --name "products" \
    --partition-key-path "/category" \
    --throughput 400

새 .NET 콘솔 애플리케이션 만들기

원하는 터미널을 사용하여 빈 폴더에 .NET 콘솔 애플리케이션을 만듭니다.

빈 폴더에서 터미널을 엽니다.
console 템플릿을 지정한 dotnet new 명령을 사용합니다.
```
dotnet new console
```

NuGet 패키지 설치

Gremlin.NET NuGet 패키지를 .NET 프로젝트에 추가합니다.

Gremlin.Net NuGet 패키지를 지정한 dotnet add package 명령을 사용합니다.
```
dotnet add package Gremlin.Net
```

dotnet build를 사용하여 .NET 프로젝트를 빌드합니다.

dotnet build

빌드가 오류 없이 성공했는지 확인합니다. 이 빌드의 예상 출력은 다음과 같습니다.

Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> \dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

환경 변수 구성

이 빠른 시작의 앞부분에서 가져오는 NAME 및 URI 값을 사용하려면 애플리케이션을 실행하는 로컬 컴퓨터의 새 환경 변수에 유지합니다.

환경 변수를 설정하려면 터미널을 사용하여 값을 각각 COSMOS_ENDPOINT 및 COSMOS_KEY로 유지합니다.
```
export COSMOS_GREMLIN_ENDPOINT="<account-name>"
export COSMOS_GREMLIN_KEY="<account-key>"
```
환경 변수가 올바르게 설정되었는지 유효성을 검사합니다.
```
printenv COSMOS_GREMLIN_ENDPOINT
printenv COSMOS_GREMLIN_KEY
```

이 문서의 코드는 cosmicworks라는 데이터베이스와 products라는 그래프에 연결됩니다. 그런 다음 코드는 추가된 항목을 트래버스하기 전에 그래프에 꼭짓점과 에지를 추가합니다.

클라이언트 인증

대부분의 Azure 서비스에 대한 애플리케이션 요청은 승인되어야 합니다. Gremlin용 API의 경우 이 빠른 시작의 앞부분에서 가져오는 NAME 및 URI 값을 사용합니다.

Program.cs 파일을 엽니다.
파일 내의 기존 콘텐츠를 삭제합니다.
Gremlin.Net.Driver 네임스페이스에 using 블록을 추가합니다.
```
using Gremlin.Net.Driver;
```

accountName 및 accountKey 문자열 변수를 만듭니다. COSMOS_GREMLIN_ENDPOINT 및 COSMOS_GREMLIN_KEY 환경 변수를 각 해당 변수의 값으로 저장합니다.

string accountName = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_ENDPOINT")!;
string accountKey = Environment.GetEnvironmentVariable("COSMOS_GREMLIN_KEY")!;

계정의 자격 증명을 사용하는 GremlinServer의 새 인스턴스 만듭니다.

var server = new GremlinServer(
    hostname: $"{accountName}.gremlin.cosmos.azure.com",
    port: 443,
    username: "/dbs/cosmicworks/colls/products",
    password: $"{accountKey}",
    enableSsl: true
);

원격 서버 자격 증명과 GraphSON 2.0 직렬 변환기를 사용하여 GremlinClient의 새 인스턴스를 만듭니다.

using var client = new GremlinClient(
    gremlinServer: server,
    messageSerializer: new Gremlin.Net.Structure.IO.GraphSON.GraphSON2MessageSerializer()
);

꼭짓점 만들기

이제 애플리케이션이 계정에 연결되었으므로 표준 Gremlin 구문을 사용하여 꼭짓점을 만듭니다.

Gremlin용 API 계정에서 서버 쪽 명령을 실행하려면 SubmitAsync을 사용합니다. 다음 속성을 사용하여 제품 꼭짓점을 만듭니다.

값

label product

id 68719518371

name Kiama classic surfboard

price 285.55

category surfboards
```
await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518371').property('name', 'Kiama classic surfboard').property('price', 285.55).property('category', 'surfboards')"
);
```

다음 속성을 사용하여 두 번째 제품 꼭짓점을 만듭니다.

	값
label	`product`
id	`68719518403`
`name`	`Montau Turtle Surfboard`
`price`	`600.00`
`category`	`surfboards`

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600.00).property('category', 'surfboards')"
);

다음 속성을 사용하여 세 번째 제품 꼭짓점을 만듭니다.

	값
label	`product`
id	`68719518409`
`name`	`Bondi Twin Surfboard`
`price`	`585.50`
`category`	`surfboards`

await client.SubmitAsync(
    requestScript: "g.addV('product').property('id', '68719518409').property('name', 'Bondi Twin Surfboard').property('price', 585.50).property('category', 'surfboards')"
);

에지 만들기

꼭짓점 간의 관계를 정의하려면 Gremlin 구문을 사용하여 에지를 만듭니다.

replaces라는 Montau Turtle Surfboard 제품에서 Kiama classic surfboard 제품에 대한 에지를 만듭니다.
```
await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))"
);
```
팁

이 에지 정의는 g.V(['<partition-key>', '<id>']) 구문을 사용합니다. 또는 g.V('<id>').has('category', '<partition-key>')를 사용할 수 있습니다.

동일한 제품에서 Bondi Twin Surfboard까지 또 다른 replaces 에지를 만듭니다.

await client.SubmitAsync(
    requestScript: "g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518409']))"
);

꼭짓점 및 에지 쿼리

Gremlin 구문을 사용하여 그래프를 탐색하고 꼭짓점 간의 관계를 찾아보세요.

그래프를 탐색하여 Montau Turtle Surfboard가 바꾸는 모든 꼭짓점을 찾습니다.

var results = await client.SubmitAsync<Dictionary<string, object>>(
    requestScript: "g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()"
);

[CREATED PRODUCT]\t68719518403 정적 문자열을 콘솔에 씁니다. 그런 다음 foreach 루프를 사용하여 일치하는 각 꼭짓점에서 반복하고 [REPLACES PRODUCT]로 시작하고 일치하는 제품 id 필드를 접미사로 포함하는 메시지를 콘솔에 씁니다.
```
Console.WriteLine($"[CREATED PRODUCT]\t68719518403");
foreach (var result in results ?? Enumerable.Empty<Dictionary<string, object>>())
{
    Console.WriteLine($"[REPLACES PRODUCT]\t{result["id"]}");
}
```

코드 실행

애플리케이션을 실행하여 애플리케이션이 예상대로 작동하는지 유효성을 검사합니다. 애플리케이션은 오류나 경고 없이 실행되어야 합니다. 애플리케이션의 출력에는 만들어지고 쿼리된 항목에 대한 데이터가 포함됩니다.

.NET 프로젝트 폴더에서 터미널을 엽니다.
애플리케이션을 실행하려면 dotnet run을 사용합니다.
```
dotnet run
```

애플리케이션의 출력을 관찰합니다.

[CREATED PRODUCT]       68719518403
[REPLACES PRODUCT]      68719518371
[REPLACES PRODUCT]      68719518409

리소스 정리

Gremlin용 API 계정이 더 이상 필요하지 않으면 해당 리소스 그룹을 삭제합니다.

아직 존재하지 않는 경우 resourceGroupName에 대한 셸 변수를 만듭니다.

# Variable for resource group name
resourceGroupName="msdocs-cosmos-gremlin-quickstart"

리소스 그룹을 삭제하려면 az group delete를 실행합니다.
```
az group delete \
    --name $resourceGroupName
```

다음 단계

Azure Cosmos DB for Apache Gremlin을 사용하여 데이터 만들기 및 쿼리

	값
label	`product`
id	`68719518371`
`name`	`Kiama classic surfboard`
`price`	`285.55`
`category`	`surfboards`