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

적용 대상: Gremlin

• 콘솔
• Python
• Node.JS
• .NET

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

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

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

필수 조건

• 활성 구독이 있는 Azure 계정.
  • Azure 구독이 없으신가요? 무료 Azure 계정을 등록합니다.
  • Azure 구독을 원하지 않으시나요? 구독 없이 Azure Cosmos DB를 무료로 사용해 볼 수 있습니다.
• Python(최신)
  • Python이 설치되어 있지 않나요? 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을 사용하려면:

1. Cloud Shell을 시작합니다.

2. 코드 블록(또는 명령 블록)에서 복사 단추를 선택하여 코드 또는 명령을 복사합니다.

3. Windows 및 Linux에서 Ctrl+Shift+V를 선택하거나 macOS에서 Cmd+Shift+V를 선택하여 코드 또는 명령을 Cloud Shell 세션에 붙여넣습니다.

4. Enter를 선택하여 코드 또는 명령을 실행합니다.

설정

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

Gremlin용 API 계정 만들기

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

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

2. 아직 로그인하지 않았다면 az login을 사용하여 Azure CLI에 로그인합니다.

3. 구독에 새 리소스 그룹을 만들려면 az group create를 사용합니다.

   az group create \
       --name $resourceGroupName \
       --location $location
   

4. 기본 설정으로 새 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 계정을 사용할 수 있으며 계정을 만들 때 옵트인해야 합니다. 이 명령이 무료 계층 할인을 적용하지 못하면 구독의 다른 계정이 이미 무료 계층으로 사용하도록 설정되었음을 의미합니다.

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

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

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

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

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

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

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

9. 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
   

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

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

1. 빈 폴더에서 터미널을 엽니다.

2. app.py 파일을 만듭니다.

   touch app.py
   

PyPI 패키지 설치

Python 프로젝트에 gremlinpython PyPI 패키지를 추가합니다.

1. requirements.txt 파일을 만듭니다.

   touch requirements.txt
   

2. Python 패키지 인덱스의 gremlinpython 패키지를 요구 사항 파일에 추가합니다.

   gremlinpython==3.7.0
   

3. 프로젝트에 모든 요구 사항을 설치합니다.

   python install -r requirements.txt
   

환경 변수 구성

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

1. 환경 변수를 설정하려면 터미널을 사용하여 값을 각각 COSMOS_ENDPOINT 및 COSMOS_KEY로 유지합니다.

   export COSMOS_GREMLIN_ENDPOINT="<account-name>"
   export COSMOS_GREMLIN_KEY="<account-key>"
   

2. 환경 변수가 올바르게 설정되었는지 유효성을 검사합니다.

   printenv COSMOS_GREMLIN_ENDPOINT
   printenv COSMOS_GREMLIN_KEY
   

코드 예제

• 클라이언트 인증
• 꼭짓점 만들기
• 에지 만들기
• 꼭짓점 및 에지 쿼리

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

클라이언트 인증

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

1. app.py 파일을 엽니다.

2. gremlin_python.driver 모듈에서 client 및 serializer를 가져옵니다.

   import os
   from gremlin_python.driver import client, serializer
   

   Warning

   Python 버전에 따라 asyncio를 가져오고 이벤트 루프 정책을 재정의해야 할 수도 있습니다.

   import asyncio
   import sys
   
   if sys.platform == "win32":
       asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
   

3. ACCOUNT_NAME 및 ACCOUNT_KEY 변수를 만듭니다. COSMOS_GREMLIN_ENDPOINT 및 COSMOS_GREMLIN_KEY 환경 변수를 각 해당 변수의 값으로 저장합니다.

   ACCOUNT_NAME = os.environ["COSMOS_GREMLIN_ENDPOINT"]
   ACCOUNT_KEY = os.environ["COSMOS_GREMLIN_KEY"]
   

4. 계정의 자격 증명과 GraphSON 2.0 직렬 변환기를 사용하여 연결하려면 Client를 사용합니다.

   client = client.Client(
       url=f"wss://{ACCOUNT_NAME}.gremlin.cosmos.azure.com:443/",
       traversal_source="g",
       username="/dbs/cosmicworks/colls/products",
       password=f"{ACCOUNT_KEY}",
       message_serializer=serializer.GraphSONSerializersV2d0(),
   )
   

꼭짓점 만들기

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

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

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

   client.submit(
       message=(
           "g.addV('product')"
           ".property('id', prop_id)"
           ".property('name', prop_name)"
           ".property('price', prop_price)"
           ".property('category', prop_partition_key)"
       ),
       bindings={
           "prop_id": "68719518371",
           "prop_name": "Kiama classic surfboard",
           "prop_price": 285.55,
           "prop_partition_key": "surfboards",
       },
   )
   

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

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

   client.submit(
       message=(
           "g.addV('product')"
           ".property('id', prop_id)"
           ".property('name', prop_name)"
           ".property('price', prop_price)"
           ".property('category', prop_partition_key)"
       ),
       bindings={
           "prop_id": "68719518403",
           "prop_name": "Montau Turtle Surfboard",
           "prop_price": 600.00,
           "prop_partition_key": "surfboards",
       },
   )
   

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

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

   client.submit(
       message=(
           "g.addV('product')"
           ".property('id', prop_id)"
           ".property('name', prop_name)"
           ".property('price', prop_price)"
           ".property('category', prop_partition_key)"
       ),
       bindings={
           "prop_id": "68719518409",
           "prop_name": "Bondi Twin Surfboard",
           "prop_price": 585.50,
           "prop_partition_key": "surfboards",
       },
   )
   

에지 만들기

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

1. replaces라는 Montau Turtle Surfboard 제품에서 Kiama classic surfboard 제품에 대한 에지를 만듭니다.

   client.submit(
       message=(
           "g.V([prop_partition_key, prop_source_id])"
           ".addE('replaces')"
           ".to(g.V([prop_partition_key, prop_target_id]))"
       ),
       bindings={
           "prop_partition_key": "surfboards",
           "prop_source_id": "68719518403",
           "prop_target_id": "68719518371",
       },
   )
   

   팁

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

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

   client.submit(
       message=(
           "g.V([prop_partition_key, prop_source_id])"
           ".addE('replaces')"
           ".to(g.V([prop_partition_key, prop_target_id]))"
       ),
       bindings={
           "prop_partition_key": "surfboards",
           "prop_source_id": "68719518403",
           "prop_target_id": "68719518409",
       },
   )
   

꼭짓점 및 에지 쿼리

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

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

   result = client.submit(
       message=(
           "g.V().hasLabel('product')"
           ".has('category', prop_partition_key)"
           ".has('name', prop_name)"
           ".outE('replaces').inV()"
       ),
       bindings={
           "prop_partition_key": "surfboards",
           "prop_name": "Montau Turtle Surfboard",
       },
   )
   

2. 이 트래버스 결과를 콘솔에 씁니다.

   print(result)
   

코드 실행

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

1. Python 프로젝트 폴더에서 터미널을 엽니다.

2. 애플리케이션을 실행하려면 python <filename>을 사용합니다. 애플리케이션의 출력을 관찰합니다.

   python app.py
   

리소스 정리

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

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

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

2. 리소스 그룹을 삭제하려면 az group delete를 실행합니다.

   az group delete \
       --name $resourceGroupName
   

다음 단계

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