快速入門：使用 Gremlin 控制台和 Azure Cosmos DB for Apache Gremlin 周遊頂點和邊緣

發行項
06/13/2024

適用於： Gremlin

Azure Cosmos DB for Apache Gremlin 是一項完全受控的圖形資料庫服務，會實作熱門的 Apache Tinkerpop (這是一種使用 Gremlin 查詢語言的圖形運算架構)。 API for Gremlin 讓使用 Gremlin 更為平順，該服務可根據您的需求以最少的管理方式進行拓展與擴增。

在本快速入門中，您將使用 Gremlin 主控台連線至新建立的 Azure Cosmos DB for Gremlin 帳戶。

必要條件

具有有效訂用帳戶的 Azure 帳戶。
- 沒有 Azure 訂閱嗎？註冊免費 Azure 帳戶。
- 不想要 Azure 訂用帳戶？您可以免費試用 Azure Cosmos DB，而不需要訂用帳戶。
Docker 主機
- 尚未安裝 Docker 嗎？請在 GitHub Codespaces 中試用本快速入門。
Azure 命令列介面 (CLI)

Azure Cloud Shell

Azure Cloud Shell 是裝載於 Azure 中的互動式殼層環境，可在瀏覽器中使用。您可以使用 Bash 或 PowerShell 搭配 Cloud Shell，與 Azure 服務共同使用。您可以使用 Cloud Shell 預先安裝的命令，執行本文提到的程式碼，而不必在本機環境上安裝任何工具。

要啟動 Azure Cloud Shell：

選項	範例/連結
選取程式碼或命令區塊右上角的 [試試看]。選取 [試試看] 並不會自動將程式碼或命令複製到 Cloud Shell 中。
請前往 https://shell.azure.com，或選取 [啟動 Cloud Shell] 按鈕，在瀏覽器中開啟 Cloud Shell。
選取 Azure 入口網站右上方功能表列上的 [Cloud Shell] 按鈕。

若要使用 Azure Cloud Shell：

啟動 Cloud Shell。
選取程式碼區塊 (或命令區塊) 上的 [複製] 按鈕以複製程式碼或命令。
透過在 Windows 和 Linux 上選取 Ctrl+Shift+V；或在 macOS 上選取 Cmd+Shift+V，將程式碼或命令貼到 Cloud Shell 工作階段中。
選取 Enter 鍵執行程式碼或命令。

建立 API for Gremlin 帳戶和相關資源

使用 Gremlin 主控台之前，請先建立 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

使用 az cosmosdb create 建立新的且具有預設設定的 API for Gremlin 帳戶。
```
az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --capabilities "EnableGremlin" \
    --locations regionName=$location \
    --enable-free-tier true
```
注意

每個 Azure 訂用帳戶最多可以有一個免費層的 Azure Cosmos DB 帳戶，而且必須在建立帳戶時選擇加入。如果該命令無法套用免費階層折扣，這表示訂用帳戶中的另一個帳戶已啟用免費階層。

使用 az cosmosdb show 取得該帳戶的 API for Gremlin 端點 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

使用 Docker 啟動及設定 Gremlin 主控台

為搭配 Gremlin 主控台，本快速入門使用來自 Docker Hub 的 tinkerpop/gremlin-console 容器映像。此映像可確保您使用適當的主控台版本 (3.4) 來連線至 API for Gremlin。主控台執行之後，請從本機 Docker 主機連線到遠端的 API for Gremlin 帳戶。

提取 3.4 版的 tinkerpop/gremlin-console 容器映像。
```
docker pull tinkerpop/gremlin-console:3.4
```

建立空的工作資料夾。在空白資料夾中，建立 remote-secure.yaml 檔案。將此 YAML 設定新增至檔案。

hosts: [<account-name>.gremlin.cosmos.azure.com]
port: 443
username: /dbs/cosmicworks/colls/products
password: <account-key>
connectionPool: {
  enableSsl: true,
  sslEnabledProtocols: [TLSv1.2]
}
serializer: {
  className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV2d0,
  config: {
    serializeResultToString: true
  }
}

注意

以本快速入門稍早取得的 NAME 和 KEY 值取代 <account-name> 和 <account-key> 預留位置。

在包含 remote-secure.yaml 檔案的工作資料夾內容中開啟新的終端。
以互動式 (--interactive --tty) 模式執行 Docker 容器映像。務必將目前的工作資料夾掛接至容器內的 /opt/gremlin-console/conf/ 路徑。
```
docker run -it --mount type=bind,source=.,target=/opt/gremlin-console/conf/ tinkerpop/gremlin-console:3.4
```
在 Gremlin 主控台容器內，使用 remote-secure.yaml 設定檔連線到遠端的 (API for Gremlin) 帳戶。
```
:remote connect tinkerpop.server conf/remote-secure.yaml
```

建立並周遊頂點和邊緣

現在主控太已連線至帳戶，請使用標準 Gremlin 語法來建立並周遊頂點和邊緣。

為具有下列屬性的產品新增頂點：

值

label product

id 68719518371

name Kiama classic surfboard

price 285.55

category surfboards
```
:> 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`
`category`	`surfboards`

:> g.addV('product').property('id', '68719518403').property('name', 'Montau Turtle Surfboard').property('price', 600).property('category', 'surfboards')

建立名為 replaces 的邊緣，以定義兩個產品之間的關聯性。

:> g.V(['surfboards', '68719518403']).addE('replaces').to(g.V(['surfboards', '68719518371']))

計算圖形內的所有頂點。
```
:> g.V().count()
```

周遊圖形並尋找所有取代 Kiama classic surfboard 的頂點。

:> g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Kiama classic surfboard').inE('replaces').outV()

周遊圖形並尋找所有被 Montau Turtle Surfboard 取代的頂點。

:> g.V().hasLabel('product').has('category', 'surfboards').has('name', 'Montau Turtle Surfboard').outE('replaces').inV()

清除資源

如果不再需要 API for Gremlin 帳戶，請刪除對應的資源群組。

如果 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 藉由提供服務形式的 Gremlin 來解決我們的問題。透過此供應，您不需要建立自己的 Gremlin 伺服器執行個體或管理您自己的基礎結構。您甚至可以在需求隨著時間增加時調整解決方案。

為了連線到 API for Gremlin 帳戶，您使用了 tinkerpop/gremlin-console 容器映像，以不需要本機安裝的方式來執行 Gremlin 主控台。然後使用儲存在 remote-secure.yaml 檔案中的設定，從執行中的容器連線到 API for Gremlin 帳戶。從該處，您執行了多個常見的 Gremlin 命令。

後續步驟

使用 Azure Cosmos DB for Apache Gremlin 建立和查詢資料

共用方式為