Visual Studio Code を使用して Azure Functions を Azure Cosmos DB に接続する

Azure Functions を使用すると、独自の統合コードを記述しなくても、Azure サービスやその他のリソースを関数に接続できます。 これらのバインドは、入力と出力の両方を表し、関数定義内で宣言されます。 バインドからのデータは、パラメーターとして関数に提供されます。 "トリガー" は、特殊な種類の入力バインドです。 関数はトリガーを 1 つしか持てませんが、複数の入力および出力バインドを持つことができます。 詳細については、「Azure Functions でのトリガーとバインドの概念」を参照してください。

この記事では、Visual Studio Code を使用して、前のクイックスタート記事で作成した関数に Azure Cosmos DB を接続する方法について説明します。 この関数に追加する出力バインドは、HTTP 要求のデータを Azure Cosmos DB コンテナーに格納された JSON ドキュメントに書き込みます。

開始する前に、「クイックスタート: Visual Studio Code を使用して Azure に C# 関数を作成する」を済ませておく必要があります。 その記事の最後でリソースをクリーンアップした場合は、もう一度手順に従って Azure で関数アプリと関連リソースを再作成してください。

開始する前に、「クイックスタート: Visual Studio Code を使用して Azure に JavaScript 関数を作成する」を済ませておく必要があります。 その記事の最後でリソースをクリーンアップした場合は、もう一度手順に従って Azure で関数アプリと関連リソースを再作成してください。

環境を構成する

作業を開始する前に、必ず Visual Studio Code 用の Azure データベース拡張機能をインストールしてください。

Azure Cosmos DB アカウントを選択する

重要

Azure Cosmos DB サーバーレスは一般公開されました。 この使用量ベースのモードにより、Azure Cosmos DB がサーバーレス ワークロードのための強力なオプションになります。 サーバーレス モードで Azure Cosmos DB を使用するには、アカウントの作成時に、 [Capacity mode]\(容量モード\) として [サーバーレス] を選択します。

  1. Visual Studio Code のアクティビティ バーで Azure アイコンを選択します。

  2. [Azure: データベース] 領域で、前の記事で関数アプリを作成した Azure サブスクリプションを右クリックし (macOS の場合は Ctrl キーを押しながらクリック)、[サーバーの作成...] を選択します。

    Visual Studio Code から新しい Azure Cosmos DB アカウントを作成する

  3. プロンプトで、次の情報を入力します。

    Prompt [選択]
    Azure データベース サーバーを選択してください SQL 構文を使用してクエリを実行できるドキュメント データベースを作成するには、Core (SQL) を選択します。 Azure Cosmos DB SQL API の詳細については、こちらを参照してください
    アカウント名 自分の Azure Cosmos DB アカウントを識別するための一意の名前を入力します。 アカウント名に使用できるのは、小文字、数字、ハイフン (-) のみで、長さは 3 文字から 31 文字の範囲にする必要があります。
    Select a capacity model (容量モデルを選択してください) サーバーレス モードでアカウントを作成するには、 [サーバーレス] を選択します。
    Select a resource group for new resources (新しいリソース用のリソース グループを選択してください) 前の記事で関数アプリを作成したリソース グループを選択します。
    Select a location for new resources (新しいリソースの場所を選択してください) Azure Cosmos DB アカウントをホストする地理的な場所を選択します。 データに最も高速にアクセスできるよう、お客様またはお客様のユーザーに最も近い場所を使用します。

    新しいアカウントがプロビジョニングされると、通知領域にメッセージが表示されます。

Azure Cosmos DB データベースとコンテナーを作成する

  1. アカウントを右クリックし、[データベースの作成] を選択します。

  2. プロンプトで、次の情報を入力します。

    Prompt [選択]
    データベース名 my-database」と入力し、
    Enter an id for your Collection (コレクションの ID を入力してください) my-container」と入力し、
    Enter the partition key for the collection (コレクションのパーティション キーを入力してください) /idとして /id を入力します。
  3. [OK] を選択してコンテナーとデータベースを作成します。

関数アプリの設定を更新する

前のクイック スタートの記事では、Azure で関数アプリを作成しました。 この記事では、作成した Azure Cosmos DB コンテナーに JSON ドキュメントを書き込むようにアプリを更新します。 Azure Cosmos DB アカウントに接続するには、その接続文字列をアプリの設定に追加する必要があります。 その後に、新しい設定を local.settings.json ファイルにダウンロードして、ローカルで実行する際に Azure Cosmos DB アカウントに接続できるようにします。

  1. Visual Studio Code で、新しい Azure Cosmos DB アカウントを右クリック (macOS の場合は Ctrl キーを押しながらクリック) し、[Copy Connection String] (接続文字列のコピー) を選択します。

    Azure Cosmos DB 接続文字列のコピー

  2. F1 キーを押してコマンド パレットを開き、コマンド を検索して実行します。

  3. 前の記事で作成した関数アプリを選択します。 プロンプトで、次の情報を入力します。

    Prompt [選択]
    新しいアプリ設定名を入力する CosmosDbConnectionString」と入力し、
    "CosmosDbConnectionString" の値を入力してください コピーした Azure Cosmos DB アカウントの接続文字列を貼り付けます。

    これに CosmosDbConnectionString より、Azure の関数アプリで接続という名前のアプリケーション設定が作成されます。 これで、この設定をローカルの設定の json ファイルにダウンロードできます。

  4. F1 キーをもう一度押してコマンド パレットを開き、コマンド を検索して実行します。

  5. 前の記事で作成した関数アプリを選択します。 [すべてはい] を選択して既存のローカル設定を上書きします。

これにより、新しい接続文字列の設定を含む、すべての設定が Azure からローカルプロジェクトにダウンロードされます。 ダウンロードした設定のほとんどは、ローカルでの実行時には使用されません。

バインディング拡張機能を登録する

Azure Cosmos DB の出力バインドを使用しているため、このプロジェクトを実行する前に対応するバインド拡張機能をインストールしておく必要があります。

HTTP トリガーとタイマー トリガーを除き、バインドは拡張機能パッケージとして実装されます。 ターミナル ウィンドウで次の dotnet add package コマンドを実行して、Azure Cosmos DB 拡張機能パッケージをプロジェクトに追加します。

dotnet add package Microsoft.Azure.WebJobs.Extensions.CosmosDB 

これで、Storage の出力バインドをプロジェクトに追加できるようになります。

プロジェクトは、拡張機能バンドルを使用するように構成されています。これにより、事前定義された一連の拡張機能パッケージが自動的にインストールされます。

拡張機能バンドルの使用は、プロジェクトのルートにある host.json ファイルで次のように有効になっています。

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[1.*, 2.0.0)"
  } 
}

これで、Azure Cosmos DB の出力バインドをプロジェクトに追加できるようになります。

出力バインディングを追加する

Functions では、各種のバインドで、directiontype、および固有の name が function.json ファイル内で定義される必要があります。 これらの属性を定義する方法は、関数アプリの言語によって異なります。

C# クラス ライブラリ プロジェクトでは、バインドは関数メソッドのバインド属性として定義されます。 その後、Functions に必要な function.json ファイルが、これらの属性に基づいて自動的に生成されます。

HttpExample.cs プロジェクト ファイルを開いて、 メソッドの定義に次のパラメーターを追加します。

[CosmosDB(databaseName: "my-database", collectionName: "my-container",
    ConnectionStringSetting = "CosmosDbConnectionString"
    )]IAsyncCollector<dynamic> documentsOut,

documentsOut パラメーターは IAsyncCollector<T> 型です。これは、関数の完了時に Azure Cosmos DB コンテナーに書き込まれる JSON ドキュメントのコレクションを表します。 特定の属性は、コンテナーとその親データベースの名前を示します。 Azure Cosmos DB アカウントの接続文字列は ConnectionStringSettingAttribute によって設定されます。

それぞれの属性は、コンテナーの名前とその親データベースの名前を指定します。 Azure Cosmos DB アカウントの接続文字列は CosmosDbConnectionString によって設定されます。

バインドの属性は、function.json ファイルで直接定義されています。 バインドの種類によっては、追加のプロパティが必要になることもあります。 Azure Cosmos DB の出力構成では、Azure Cosmos DB 出力バインドに必要なフィールドについて説明します。 この拡張機能により、バインドを簡単に function.json ファイルに追加できます。

バインドを作成するには、HttpTrigger フォルダー内の function.json ファイルを右クリック (macOS では Ctrl キーを押しながらクリック) して、function.json を選択します。プロンプトに従って、新しいバインドの次のバインド プロパティを定義します。

Prompt 説明
Select binding direction (バインド方向を選択する) out バインドは出力バインドです。
Select binding with direction "out" ("外" 方向のバインドを選択する) Azure Cosmos DB バインドは Azure Cosmos DB バインドです。
コードでこのバインドの特定に使用する名前 outputDocument コードで参照されているバインド パラメーターを識別する名前。
データを書き込む Cosmos DB データベース my-database ターゲット コンテナーを含む Azure Cosmos DB データベースの名前。
データが書き込まれるデータベース コレクション my-container JSON ドキュメントが書き込まれる Azure Cosmos DB コンテナーの名前。
[If true, creates the Cosmos DB database and collection]\(オンの場合、Cosmos DB データベースとコレクションを作成する\) false ターゲットのデータベースとコンテナーは既に存在します。
Select setting from "local.setting.json" ("local.setting.json" から設定を選択する) CosmosDbConnectionString Azure Cosmos DB アカウントの接続文字列を含むアプリケーション設定の名前。
パーティション キー (省略可能) 空白のまま 出力バインドによってコンテナーが作成される場合にのみ必須です。
コレクションのスループット (省略可能) 空白のまま 出力バインドによってコンテナーが作成される場合にのみ必須です。

バインドは、function.json の bindings 配列に追加されます。このファイルは次のようになります。

{
    "type": "cosmosDB",
    "direction": "out",
    "name": "outputDocument",
    "databaseName": "my-database",
    "collectionName": "my-container",
    "createIfNotExists": "false",
    "connectionStringSetting": "CosmosDbConnectionString"
}

出力バインディングを使用するコードを追加する

documentsOut 出力バインド オブジェクトを使用して JSON ドキュメントを作成するコードを追加します。 このコードは、メソッドから制御が戻る前に追加します。

if (!string.IsNullOrEmpty(name))
{
    // Add a JSON document to the output container.
    await documentsOut.AddAsync(new
    {
        // create a random ID
        id = System.Guid.NewGuid().ToString(),
        name = name
    });
}

この時点で、関数は次のようになります。

[FunctionName("HttpExample")]
public static async Task<IActionResult> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
    [CosmosDB(
        databaseName: "my-database",
        collectionName: "my-container",
        ConnectionStringSetting = "CosmosDbConnectionString")]IAsyncCollector<dynamic> documentsOut,
    ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    string name = req.Query["name"];

    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);
    name = name ?? data?.name;

    if (!string.IsNullOrEmpty(name))
    {
        // Add a JSON document to the output container.
        await documentsOut.AddAsync(new
        {
            // create a random ID
            id = System.Guid.NewGuid().ToString(),
            name = name
        });
    }

    string responseMessage = string.IsNullOrEmpty(name)
        ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
        : $"Hello, {name}. This HTTP triggered function executed successfully.";

    return new OkObjectResult(responseMessage);
}

context.bindingsoutputDocument 出力バインド オブジェクトを使用して JSON ドキュメントを作成するコードを追加します。 このコードを context.res ステートメントの前に追加します。

if (name) {
    context.bindings.outputDocument = JSON.stringify({
        // create a random ID
        id: new Date().toISOString() + Math.random().toString().substr(2,8),
        name: name
    });
}

この時点で、関数は次のようになります。

module.exports = async function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    const name = (req.query.name || (req.body && req.body.name));
    const responseMessage = name
        ? "Hello, " + name + ". This HTTP triggered function executed successfully."
        : "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response.";

    if (name) {
        context.bindings.outputDocument = JSON.stringify({
            // create a random ID
            id: new Date().toISOString() + Math.random().toString().substr(2,8),
            name: name
        });
    }

    context.res = {
        // status: 200, /* Defaults to 200 */
        body: responseMessage
    };
}

このコードは、ドキュメントと HTTP 応答の両方を含む MultiResponse オブジェクトを返すようになりました。

関数をローカルで実行する

Visual Studio Code を Azure Functions Core Tools と統合することで、このプロジェクトをローカルの開発用コンピューター上で実行してから、Azure に発行することができます。

  1. 関数を呼び出すには、F5 キーを押して関数アプリ プロジェクトを起動します。 Core Tools からの出力がターミナル パネルに表示されます。 アプリがターミナル パネルで起動します。 HTTP によってトリガーされる関数の URL エンドポイントがローカルで実行されていることを確認できます。

    ローカル関数の VS Code の出力

    Windows での実行に問題がある場合、Visual Studio Code の既定のターミナルが WSL Bash に設定されていないことをご確認ください。

  2. Core Tools を実行したまま、Azure: Functions 領域に移動します。 [Functions][ローカル プロジェクト][Functions] を展開します。 関数を右クリック (Windows) または Ctrl キーを押しながらクリック (macOS) して、[Execute Function Now]\(今すぐ関数を実行\) を選択します。

    Visual Studio Code から今すぐ関数を実行する

  3. [Enter request body]\(要求本文を入力してください\) で、Enter キーを押して要求メッセージを関数に送信します。

  4. ローカルで関数を実行し、応答が返されると、Visual Studio Code で通知が発生します。 関数の実行に関する情報は、 [ターミナル] パネルに表示されます。

  5. Ctrl + C キーを押して Core Tools を停止し、デバッガーの接続を解除します。

関数をローカルで実行する

  1. 前の記事と同様、F5 キーを押して関数アプリ プロジェクトと Core Tools を起動します。

  2. Core Tools を実行したまま、Azure: Functions 領域に移動します。 [Functions][ローカル プロジェクト][Functions] を展開します。 HttpExample 関数を右クリック (Mac では Ctrl キーを押しながらクリック) し、HttpExample を選択します。

    Visual Studio Code から今すぐ関数を実行する

  3. [Enter request body]\(要求本文を入力してください\) に、要求メッセージ本文の値として が表示されます。 Enter キーを押して、この要求メッセージを関数に送信します。

  4. 応答が返されたら、Ctrl + C キーを押して Core Tools を停止します。

JSON ドキュメントが作成されたことを確認する

  1. Azure portal で Azure Cosmos DB アカウントに戻り、 [データ エクスプローラー] を選択します。

  2. データベースとコンテナーを展開し、 [項目] を選択して、コンテナー内に作成されたドキュメントを一覧表示します。

  3. 出力バインドによって新しい JSON ドキュメントが作成されたことを確認します。

    Azure Cosmos DB コンテナーに新しいドキュメントが作成されたことを確認する

更新したアプリを再デプロイして検証する

  1. Visual Studio Code で、F1 キーを押してコマンド パレットを開きます。 コマンド パレットで、Azure Functions: Deploy to function app... を検索して選択します。

  2. 最初の記事で作成した関数アプリを選択します。 同じアプリにプロジェクトを再デプロイしているため、 [デプロイ] を選択して、ファイルの上書きに関する警告を無視します。

  3. デプロイの完了後、もう一度 [Execute Function Now]\(今すぐ関数を実行\) 機能を使用して Azure で関数をトリガーできます。

  4. この場合も Azure Cosmos DB コンテナーに作成されたドキュメントを確認し、出力バインドによって再び新しい JSON ドキュメントが生成されていることを確認します。

リソースをクリーンアップする

Azure では、"リソース" とは、関数アプリ、関数、ストレージ アカウントなどのことを指します。 これらは "リソース グループ" に分類されており、グループを削除することでグループ内のすべてのものを削除できます。

これらのクイックスタートを完了するためにリソースを作成しました。 これらのリソースには、アカウントの状態サービスの価格に応じて課金される場合があります。 リソースの必要がなくなった場合にそれらを削除する方法を、次に示します。

  1. Visual Studio Code で、F1 キーを押してコマンド パレットを開きます。 コマンド パレットで、Azure Functions: Open in portal を検索して選択します。

  2. 関数アプリを選択し、Enter キーを押します。 その関数アプリのページが Azure portal で開きます。

  3. [概要] タブで、 [リソース グループ] の横にある名前付きリンクを選択します。

    関数アプリのページから削除するリソース グループを選択する。

  4. [リソース グループ] ページで、含まれているリソースの一覧を確認し、削除するものであることを確認します。

  5. [リソース グループの削除] を選択し、指示に従います。

    削除には数分かかることがあります。 実行されると、通知が数秒間表示されます。 ページの上部にあるベルのアイコンを選択して、通知を表示することもできます。

次のステップ

JSON ドキュメントが Azure Cosmos DB コンテナーに書き込まれるように、HTTP によってトリガーされる関数を更新しました。 この後は、Visual Studio Code を使用した Functions の開発について理解を深めましょう。