快速入門：適用於 Apache Gremlin 的 Azure Cosmos DB 連結庫，適用於 Node.js

  • 發行項

適用於： Gremlin

適用於 Apache Gremlin 的 Azure Cosmos DB 是完全受控的圖形資料庫服務，使用 Gremlin 查詢語言實作熱門 Apache Tinkerpop的圖表運算架構。 Gremlin 的 API 可讓您以低摩擦的方式開始使用 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 中。 Screenshot that shows an example of Try It for Azure Cloud Shell.
請前往 https://shell.azure.com，或選取 [啟動 Cloud Shell] 按鈕，在瀏覽器中開啟 Cloud Shell。 Button to launch Azure Cloud Shell.
選取 Azure 入口網站右上方功能表列上的 [Cloud Shell] 按鈕。 Screenshot that shows the Cloud Shell button in the Azure portal

若要使用 Azure Cloud Shell：

  1. 啟動 Cloud Shell。

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

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

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

設定

本節將逐步引導您建立 Gremlin 帳戶的 API，並設定Node.js專案以使用連結庫來連線到帳戶。

建立 Gremlin 帳戶的 API

使用 Node.js 連結庫之前，應該先建立 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. 使用 az cosmosdb create 建立具有預設設定之 Gremlin 帳戶的新 API。

    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取得帳戶的 Gremlin 端點名稱 API。

    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 服務的應用程式要求都必須獲得授權。 針對 Gremlin 的 API，請使用 本快速入門稍早取得的 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 在 Gremlin 帳戶的 API 上執行命令伺服器端。 使用下列屬性建立 產品 頂點：

    值
    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. 使用下列屬性建立第二 個產品 頂點：

    值
    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. 使用下列屬性建立第三 個產品 頂點：

    值
    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產品。

    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。

    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

清除資源

當您不再需要 Gremlin 帳戶的 API 時，請刪除對應的資源群組。

  1. 如果 resourceGroupName 不存在，請建立殼層變數。

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

  2. 使用 az group delete 來刪除資源群組。

    az group delete \
    --name $resourceGroupName

後續步驟

使用適用於 Apache Gremlin 的 Azure Cosmos DB 建立和查詢數據