練習 - 使用輸入繫結讀取資料

20 分鐘

假設您想要建立書籤查閱服務。您的服務一開始為唯讀。若使用者想要尋找項目，他們會傳送具有項目識別碼的要求，而我們的函式則會傳回 URL。下列流程圖說明邏輯流程。

當使用者以文字傳送要求時，尋找書籤函式會嘗試在資料庫 (其中包含具有作為索引碼或識別碼之文字的書籤) 中尋找輸入。系統會傳回結果，指出您是否找到該項目。

當 Azure 函式接收具有書籤識別碼的要求時，其會先檢查要求是否有效。若無效，則會產生錯誤回應。若要求有效，則函式會檢查 Azure Cosmos DB 資料庫中是否有該書籤識別碼存在。若不存在，則會產生錯誤回應。如果找到書籤識別碼，則會產生成功回應。

您需要將資料儲存在某個位置。在之前的流程圖中，資料存放區為 Azure Cosmos DB 執行個體。但是該如何從函式連線至資料庫並讀取資料？在函式的世界中，您會為該作業設定「輸入繫結」。透過 Azure 入口網站設定輸入繫結，是相當直截了當的做法。如同您即將看到的內容，不必撰寫程式碼或開啟儲存體連線。 Azure Functions 執行階段和繫結會為您進行那些工作。

建立 Azure Cosmos DB 帳戶

注意

此練習並非 Azure Cosmos DB 的教學課程。如果有興趣深入了解，請參閱此課程模組結尾的 Azure Cosmos DB 完整學習路徑。

建立資料庫帳戶

資料庫帳戶為用來管理一或多個資料庫的容器。我們需要先建立資料庫帳戶，才能建立資料庫。

請在 Azure 入口網站資源功能表中或從 [首頁] 頁面，選取 [建立資源]。 [建立資源] 窗格隨即會顯示。
請在 [建立資源] 功能表中，選取 [資料庫]，然後搜尋並選取 [Azure Cosmos DB]。 [哪個 API 最適合您的工作負載？] 窗格隨即出現。
請在 [Azure Cosmos DB for NoSQL] 選項中，選取 [建立]，以利於建立 Cosmos DB 觸發程序與輸入/輸出繫結。 [建立 Azure Cosmos DB 帳戶 - Azure Cosmos DB for NoSQL] 窗格隨即出現。

在 [基本] 索引標籤上，為每個設定輸入下列值。

設定	值	Description
專案詳細資料
訂用帳戶	指引訂用帳戶	適用於沙箱中資源的 Azure 訂閱。
資源群組	從下拉式清單中選取 [沙箱資源群組名稱]	您的沙箱資源群組。
執行個體詳細資料
客戶名稱	`globally unique name`	輸入您 Azure Cosmos DB 帳戶的唯一但可識別的名稱；`documents.azure.com` 會附加至您提供的名稱。 `3 - 50 lowercase characters, numbers, or hyphens (-)`.
位置	`region`	選取最靠近區域。

接受其餘設定的預設值，然後選取 [檢閱 + 建立] 以驗證您的輸入。 [驗證成功] 通知隨即出現。
請選取 [建立] 以佈建並部署資料庫帳戶。
部署可能需要一些時間。在繼續之前，請等候通知中樞的部署成功訊息。
選取 [移至資源] 以移至入口網站中的資料庫帳戶。您 Azure Cosmos DB 帳戶的 [快速入門] 窗格隨即出現。

接下來，我們會新增容器，接著將資料庫新增至 Azure Cosmos DB 帳戶。

新增容器

在 Azure Cosmos DB 中，會使用「容器」來儲存各種使用者產生的實體，也稱為「項目」。我們會建立名為「書籤」的容器。

使用 [資料總管] 工具來建立資料庫與容器。

請在您的 [Azure Cosmos DB 帳戶] 功能表中，選取 [資料總管]。隨即出現 Cosmos DB 帳戶的 [資料總管] 窗格。
選取 [新增容器] 方塊。 [新增容器] 窗格隨即出現。您可能需要捲動才會看見它。

針對每個設定輸入下列值。

設定	值	Description
資料庫識別碼	請選取 [新建]，並輸入 func-io-learn-db 做為資料庫識別碼	資料庫名稱的長度必須為 1 到 255 個字元，且不得包含 `/, \\, #, ?` 或後置空格。您可以輸入任何內容，但在此課程模組中，我們會使用 func-io-learn-db。
資料庫最大值，RU/秒	4000	接受每秒 4000 個要求單位 (RU/秒) 的預設輸送量。如果要降低延遲，稍後可以擴大效能。
容器識別碼	書籤	容器識別碼與資料庫名稱具有相同的字元需求。我們在此課程模組中會使用「書籤」。
分割區索引鍵	/id	分割區索引鍵會指定 Azure Cosmos DB 集合中的文件跨邏輯資料分割區散發的方式。為了方便起見，在此我們使用 [分割區索引鍵] 設定，因為在此課程模組中不需在意資料庫效能。如果要深入了解 Azure Cosmos DB 分割區索引鍵策略，請探索 Microsoft Learn Azure Cosmos DB 課程模組。

接受所有其他設定的預設值。

請捲動至窗格底部，並選取 [確定]。花幾分鐘的時間等候資料庫與容器建置完成。

完成時，[資料總管] 會在 [NOSQL API] 底下的 [DATA] 中顯示 func-io-learn-db。
請選取 [func-io-learn-db] 以將其展開。請注意，您的 func-io-learn-db 資料庫包含數個子項目成員 (其中包括「縮放」與「書籤)。
展開 [書籤] 容器。請注意，數個子成員已預先填入它。

在下一個工作中，您要將某些資料 (也稱為項目) 新增至您的「書籤」容器。

新增測試資料

您想要將資料新增至「書籤」容器。請使用 [資料總管] 來儲存每個項目的 URL 與識別碼。

請展開 func-io-learn-db 資料庫並展開「書籤」容器，然後選取 [項目]。 [項目] 索引標籤隨即顯示。
請在命令列中，選取 [新增項目]。

將下列 JSON 程式碼取代為新項目的預設程式碼。

{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}

在命令列中，選取 [儲存]。

請注意，出現比已新增的兩行屬性還要多的屬性。其屬性皆以底線 (_rid, _self, _etag, _attachments, _ts) 為開頭。下表所述的這些屬性由系統所產生，用於協助管理您新增至容器的項目。

屬性	說明
`_rid`	資源識別碼是唯一識別碼，同時也是資源模型上，由資源堆疊的階層式。識別碼可在內部用來放置和瀏覽項目資源。
`_self`	資源的唯一可定址 URI。
`_etag`	開放式同步存取控制項的必要項目。
`_attachments`	附件資源的可定址路徑。
`_ts`	此資源上次更新的時間戳記。

讓我們再將一些項目新增至「書籤」容器。請在命令列中，選取 [新增項目]。使用下列內容來建立額外四個項目。選取 [新增項目]，然後在複製並貼上每個新項目之後選取 [儲存]，即可新增項目。請注意每個項目新增至項目清單的方式。
```
{
    "id": "portal",
    "url": "https://portal.azure.com"
}
```
```
{
    "id": "learn",
    "url": "https://learn.microsoft.com/training"
}
```
```
{
    "id": "marketplace",
    "url": "https://azuremarketplace.microsoft.com/marketplace/apps"
}
```
```
{
    "id": "blog",
    "url": "https://azure.microsoft.com/blog"
}
```
當您完成輸入書籤資料時，您的容器應該會如下圖所示。

您的「書籤」容器有五個項目。在此案例中，如果送達的要求有 "id=docs"，則其會在您的「書籤」容器中查閱該識別碼，然後傳回 URL https://learn.microsoft.com/azure。建立 Azure 函式來查閱您「書籤」容器中的值。

建立函式

移至您在上一個單元中所建立的函式應用程式。請在資源功能表中，選取 [首頁]，然後在 [最近的資源] 區段中，您應該會看到函數應用程式 ([類型] 等於 [函數應用程式])。選取函數應用程式。隨即出現 [函數應用程式] 窗格。
在 [概觀] 頁面的 [函式] 索引標籤中，您應該會有一個函式，HTTP 觸發程式1。
我們來建立另一個函式。在 [函式] 索引標籤上，選取 [建立]。隨即出現 [建立函式] 窗格，並列出受支援觸發程序的範本。
在 [選取範本] 區段中，選取 [HTTP 觸發程序]，然後選取 [下一步]。
接受所有預設設定，然後選取 [建立] 以建立您的函式。

隨即出現 HttpTrigger2 函式的 [概觀] 窗格。

驗證函式

到目前為止，您可以測試新的函式來確認我們的進度。

在命令列中，選取 [取得函式 URL]。 [取得函式 URL] 對話方塊隨即顯示。
從下拉式清單中選取 [預設 (功能鍵)]，然後選取 [複製至剪貼簿] 圖示，並選取 [確定]。
將您複製的函式 URL 貼至新的瀏覽器索引標籤的網址列中。將查詢字串值&name=<your name>附加至 URL 結尾，並以您的名稱取代<your name>，然後按 Enter。 Azure 函式應該會在瀏覽器中傳回個人化回應。

現在我們已經能讓基本的函式正常運作，接下來請關注如何從 Azure Cosmos DB (或在我們的案例中，從您的「書籤」容器) 中讀取資料。

新增 Azure Cosmos DB 輸入繫結

如果要從資料庫讀取資料，您必須定義輸入繫結。如您在此所見，只需幾個步驟，您即可設定可與您的資料庫對話的繫結。

在 Azure 入口網站上方的 [HttpTrigger2] 函式功能表中，選取 [整合]。隨即出現您函式的 [整合] 窗格。

您已使用範本來建立具有 HTTP 輸出繫結的 HTTP 觸發程序要求。接著，新增 Azure Cosmos DB 輸入繫結。
在 [觸發程序和輸入] 方塊中，選取 [新增輸入]。 [建立輸入] 窗格隨即出現。
從 [繫結類型] 下拉式清單中，選取 [Azure Cosmos DB]。
在 [Azure Cosmos DB 詳細資料] 區段中，於 [Cosmos DB 帳戶連線] 設定下選取 [新增] 連結。 [新增 Cosmos DB 連線] 對話方塊隨即出現。

如果出現安裝 Microsoft.Azure.WebJobs.Extensions.CosmosDB 延伸模組的提示訊息，請選取 [安裝] 並等候其完成。
根據預設，Azure 會辨識您稍早建立的 Azure Cosmos DB 帳戶。請選取 [確定] 以設定與資料庫的連線。已設定資料庫帳戶的「新」連線，並顯示於 [Cosmos DB 帳戶連線] 欄位中。

我們想要查詢具有特定識別碼的書籤，因此讓我們將在查詢字串中接收到的識別碼繫結至繫結上。

讓我們在 [建立輸入] 窗格中完成設定。針對每個設定輸入下列值。如果要深入了解每個設定的用途，請選取該欄位的資訊圖示。

設定	值	Description
文件參數名稱	`bookmark`	用來識別程式碼中此繫結的名稱。
資料庫名稱	`func-io-learn-db`	要使用的資料庫。此值是我們所設定的資料庫名稱。
集合名稱	`Bookmarks`	我們從中讀取資料的集合。此設定已定義。
文件識別碼	`id`	新增我們在建立「書籤」Azure Cosmos DB 容器時所定義的文件識別碼。
分割區索引鍵	`/id`	新增您在建立「書籤」Azure Cosmos DB 集合時所定義的分割區索引鍵。在此處輸入的索引鍵 (在輸入繫結格式 `<key>` 中指定) 必須與集合中的相符。
SQL 查詢 (選擇性)	保留空白	您只會根據識別碼一次擷取一份文件。因此，使用 [文件識別碼] 設定篩選，比在這個執行個體中使用 SQL 查詢還要好。您可以建立 SQL 查詢以傳回一個項目 (`SELECT * from b where b.ID = id`)。該查詢確實會傳回文件，但其會在文件集合中傳回。您的程式碼可能會進行不必要地操作集合。您想要取得多份文件時，請使用 SQL 查詢方法。

為了闡明使用這些設定的原因，我們想要查詢具有特定識別碼的書籤，因此我們將函式在查詢字串中接收的「文件識別碼」繫結至輸入繫結。此語法也稱為「繫結運算式」。函式會由 HTTP 要求觸發，該 HTTP 要求會使用查詢字串指定要查閱的識別碼。由於識別碼在集合中是唯一的，因此繫結會傳回 0 份 (找不到) 或 1 份 (找到) 文件。

如果要儲存此輸入繫結設定，請選取 [新增]。

更新該函式實作

既然已定義您的繫結，您即可在函式中使用此繫結。您需要做出兩項變更，才能實作剛建立的繫結：

修改函式的特定語言實作程式碼。這個步驟需要確定在資料庫中所找到的文件是否和傳遞給函式的識別碼相符。
請修改函式的 JSON 實作程式碼，以接受在查詢字串中傳遞的參數。

修改函式的 JavaScript 執行程式碼

請在 HttpTrigger2 函式的 [函式] 功能表中，選取 [程式碼 + 測試]。隨即出現 HttpTrigger2 函式的 [程式碼 + 測試] 窗格。

以下列程式碼取代 index.js 檔案中的所有程式碼。

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark

    if(bookmark){
        context.res = {
        body: { "url": bookmark.url },
        headers: {
            'Content-Type': 'application/json'
        }
        };
    }
    else {
        context.res = {
            status: 404,
            body : "No bookmarks found",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }

    context.done();
};

在命令列中，選取 [儲存]。在 [記錄] 窗格頂端的下拉式清單中選取 [檔案系統記錄]，(預設會顯示 [App Insights 記錄])。隨即出現 [記錄] 窗格，顯示您已具有 Connected!

讓我們來檢驗此程式碼的作用。

傳入 HTTP 要求隨即觸發函式，而且系統會將 id 查詢參數傳遞至 Azure Cosmos DB 輸入繫結。
如果資料庫找到和此識別碼相符的文件，則會將 bookmark 參數設為所找到的文件。

在此範例中，程式碼會建立回應，其中包含在資料庫的對應文件中找到的 URL 值。
如果找不到符合此索引鍵的文件，則要求會以承載與狀態碼回應來告知使用者壞消息。

修改函式的 JSON 實作程式碼

從 <functionapp> \ HttpTrigger2 \ 路徑的下拉式清單中，選取 [function.json]。

以下列程式碼取代 function.json 檔案中的所有程式碼。務必以 Azure Cosmos DB 帳戶的名稱取代 your-database。

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "partitionKey": "{id}",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "id": "{id}",
    }
  ]
}

在命令列中，選取 [儲存]。

修改函式的 PowerShell 實作程式碼

請在 HttpTrigger2 函式的 [函式] 功能表中，選取 [程式碼 + 測試]。隨即出現 HttpTrigger2 函式的 [程式碼 + 測試] 窗格，並顯示 run.ps1 檔案。

用下列程式碼取代 run.ps1 檔案中的所有程式碼。

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = [HttpStatusCode]::OK
    $body = @{ url = $bookmark.url }
}
else {
    $status = [HttpStatusCode]::NotFound
    $body = "No bookmarks found"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
})

在命令列中，選取 [儲存]。在 [記錄] 窗格頂端的下拉式清單中選取 [檔案系統記錄]，(預設會顯示 [App Insights 記錄])。隨即出現 [記錄] 窗格，顯示您已具有 Connected!

讓我們來檢驗此程式碼的作用。

傳入 HTTP 要求隨即觸發函式，而且系統會將 id 查詢參數傳遞至 Azure Cosmos DB 輸入繫結。
如果資料庫找到和此識別碼相符的文件，則會將 bookmark 參數設為所找到的文件。

在此範例中，程式碼會建立回應，其中包含在資料庫的對應文件中找到的 URL 值。
如果找不到符合此索引鍵的文件，則要求會以承載與狀態碼回應來告知使用者壞消息。

修改函式的 JSON 實作程式碼

從 <functionapp> \ HttpTrigger2 \ 路徑的下拉式清單中，選取 [function.json]。

修改 id 和 partitionKey 的值，使其接受 {id} 的參數。您的 function.json 程式碼應該與下列範例類似，其中會用 Cosmos DB 資料庫的名稱取代 your-database。

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "cosmosDB",
      "name": "bookmark",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "direction": "in",
      "id": "{id}",
      "partitionKey": "{id}"
    }
  ]
}

在命令列中，選取 [儲存]。

試試看

您應該已經位於 HttpTrigger2 函式的 [程式碼 + 測試] 窗格中。
在命令列中，選取 [取得函式 URL]。 取得函式 URL 對話方塊隨即顯示。
從 [金鑰] 下拉式清單中，選取 [功能鍵] 底下的 [預設]，然後選取 URL 結尾的 [複製至剪貼簿] 圖示。
將複製的函式金鑰貼到新瀏覽器索引標籤的網址列中，然後將查詢字串值 &id=docs 新增至 URL 的結尾。產生的 URL 應該會與下列範例類似：

https://example.azurewebsites.net/api/HttpTrigger2?code=AbCdEfGhIjKlMnOpQrStUvWxYz==&id=docs
按 Enter 以執行該要求。函式傳回的回應，應該會與下列範例類似。
```
{
  "url": "https://learn.microsoft.com/azure"
}
```
以 &id=missing 取代 &id=docs、按 Enter 並且觀察其回應。我們已定義五個書籤，並在要求的書籤不存在時，建立具意義的錯誤回應。

在此單元中，您手動建立了第一個輸入繫結，以便從 Azure Cosmos DB 資料庫讀取。多虧有繫結，讓您只要撰寫最少的程式碼，即可搜尋資料庫及讀取資料。您花費大部分的心力，以宣告方式設定繫結，該平台會負責剩餘的工作。

在下一個單元中，您會透過 Azure Cosmos DB 輸出繫結，將更多資料新增至我們的書籤集合。

練習 - 使用輸入繫結讀取資料

建立 Azure Cosmos DB 帳戶

建立資料庫帳戶

新增容器

新增測試資料

建立函式

驗證函式

新增 Azure Cosmos DB 輸入繫結

更新該函式實作

修改函式的 JavaScript 執行程式碼

修改函式的 JSON 實作程式碼

修改函式的 PowerShell 實作程式碼

修改函式的 JSON 實作程式碼

試試看

意見反應