共用方式為

快速入門：適用於 Node.js 的 Azure Cosmos DB for Apache Gremlin 程式庫

  • 發行項

適用於： Gremlin

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

在本快速入門中，您將使用 gremlin 程式庫連線至新建立的 Azure Cosmos DB for Gremlin 帳戶。

程式庫原始程式碼 | 套件 (npm)

必要條件

Azure Cloud Shell

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

要啟動 Azure Cloud Shell：

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

若要使用 Azure Cloud Shell：

  1. 啟動 Cloud Shell。

  2. 選取程式碼區塊 (或命令區塊) 上的 [複製] 按鈕以複製程式碼或命令。

  3. 透過在 Windows 和 Linux 上選取 Ctrl+Shift+V；或在 macOS 上選取 Cmd+Shift+V，將程式碼或命令貼到 Cloud Shell 工作階段中。

  4. 選取 Enter 鍵執行程式碼或命令。

設定

本節將逐步引導您建立 API for Gremlin 帳戶，並設定 Node.js 專案以使用程式庫連線至該帳戶。

建立 API for Gremlin 帳戶

使用 Node.js 程式庫之前，請先建立 API for Gremlin 帳戶。 此外，該帳戶還有助於建立資料庫和圖形。

  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. 使用 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 帳戶，而且必須在建立帳戶時選擇加入。 如果該命令無法套用免費階層折扣，這表示訂用帳戶中的另一個帳戶已啟用免費階層。

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

建立新的 Node.js 主控台應用程式

使用您慣用的終端機，在空白資料夾中建立 Node.js 主控台應用程式。

  1. 在空資料夾中開啟終端機。

  2. 初始化新的模組

    npm init es6 --yes

  3. 建立 app.js 檔案

    touch app.js

安裝 npm 套件

將 gremlin npm 套件新增至 Node.js 專案。

  1. 開啟 package.json 檔案，並將該檔案內容取代為此 JSON 設定。

    {
  "main": "app.js",
  "type": "module",
  "scripts": {
    "start": "node app.js"
  },
  "dependencies": {
    "gremlin": "^3.*"
  }
}

  2. 使用 npm install 命令來安裝 package.json 檔案中指定的所有套件。

    npm install

設定環境變數

若要使用本快速入門前面所取得的 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 服務的應用程式要求都必須獲得授權。 若為 API for Gremlin，請使用本快速入門前面所取得的 NAME 和 URI 值。

  1. 開啟 app.js 檔案。

  2. 匯入 gremlin 模組。

    import gremlin from 'gremlin'

  3. 建立 accountName 和 accountKey 變數。 將 COSMOS_GREMLIN_ENDPOINT 和 COSMOS_GREMLIN_KEY 環境變數儲存為每個個別變數的值。

    const accountName = process.env.COSMOS_GREMLIN_ENDPOINT
const accountKey = process.env.COSMOS_GREMLIN_KEY

  4. 使用 PlainTextSaslAuthenticator 為帳戶憑證建立新物件。

    const credentials = new gremlin.driver.auth.PlainTextSaslAuthenticator(
  '/dbs/cosmicworks/colls/products',
  `${accountKey}`
)

  5. 使用 Client 透過遠端伺服器認證和 GraphSON 2.0 序列化程式進行連線。 然後，使用 Open 來建立與伺服器的新連線。

    const client = new gremlin.driver.Client(
  `wss://${accountName}.gremlin.cosmos.azure.com:443/`,
  {
    credentials,
    traversalsource: 'g',
    rejectUnauthorized: true,
    mimeType: 'application/vnd.gremlin-v2.0+json'
  }
)

client.open()

建立頂點

現在應用程式已連線至帳戶，請使用標準 Gremlin 語法來建立頂點。

  1. 使用 submit 在 API for Gremlin 帳戶上執行伺服器端命令。 建立具有以下屬性的 product 頂點：

    值
    label product
    id 68719518371
    name Kiama classic surfboard
    price 285.55
    category surfboards 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518371',
    prop_name: 'Kiama classic surfboard',
    prop_price: 285.55,
    prop_partition_key: 'surfboards'
  }
)

  2. 建立具有下列屬性的第二個 product 頂點：

    值
    label product
    id 68719518403
    name Montau Turtle Surfboard
    price 600.00
    category surfboards 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518403',
    prop_name: 'Montau Turtle Surfboard',
    prop_price: 600.00,
    prop_partition_key: 'surfboards'
  }
)

  3. 建立具有下列屬性的第三個 product 頂點：

    值
    label product
    id 68719518409
    name Bondi Twin Surfboard
    price 585.50
    category surfboards 
    await client.submit(
  'g.addV(\'product\').property(\'id\', prop_id).property(\'name\', prop_name).property(\'price\', prop_price).property(\'category\', prop_partition_key)', {
    prop_id: '68719518409',
    prop_name: 'Bondi Twin Surfboard',
    prop_price: 585.50,
    prop_partition_key: 'surfboards'
  }
)

建立邊緣

使用 Gremlin 語法建立邊緣，以定義頂點之間的關聯性。

  1. 建立從 Montau Turtle Surfboard 產品到 Kiama classic surfboard 產品且名為 replaces 的邊緣。

    await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    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 邊緣。

    await client.submit(
  'g.V([prop_partition_key, prop_source_id]).addE(\'replaces\').to(g.V([prop_partition_key, prop_target_id]))', {
    prop_partition_key: 'surfboards',
    prop_source_id: '68719518403',
    prop_target_id: '68719518409'
  }
)

查詢頂點和邊緣

使用 Gremlin 語法周遊圖形，並探索頂點之間的關聯性。

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

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

  2. 將此遍訪結果寫入主控台。

    console.dir(result)

執行程式碼

透過執行應用程式來驗證您的應用程式是否如預期運作。 應用程式執行時應該沒有任何錯誤或警告。 應用程式的輸出包含已建立和已查詢項目的相關資料。

  1. 在 Node.js 專案資料夾中開啟終端機。

  2. 使用 npm <script> 執行應用程式。 觀察應用程式的輸出。

    npm start

清除資源

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

  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 建立和查詢資料