SDK を使ってユーザー定義関数を実装してから使用する

Azure Cosmos DB for NoSQL 用の .NET SDK 使用して、コンテナーから直接サーバー側のプログラミングコンストラクトを管理し、呼び出すことができます。新しいコンテナーを準備する際、データエクスプローラーを使用して手動でタスクを実行する代わりに、.NET SDK を使用して UDF をコンテナーに直接発行する方が理にかなっている場合があります。

このラボでは、.NET SDK を使用して新しい UDF を作成し、データエクスプローラーを使用して UDF が正常に機能していることを検証します。

開発環境を準備する

このラボで作業している環境に DP-420 のラボコードのリポジトリをまだクローンしていない場合は、次の手順に従ってクローンします。それ以外の場合は、以前にクローンしたフォルダーを Visual Studio Code で開きます。

Visual Studio Code を起動します。

📝 Visual Studio Code インターフェイスについてまだよく理解していない場合は、Visual Studio Code の入門ガイドを参照してください
コマンドパレットを開き、Git: Clone を実行して、任意のローカルフォルダーに https://github.com/microsoftlearning/dp-420-cosmos-db-dev GitHub リポジトリをクローンします。

💡 Ctrl + Shift + P キーボードショートカットを使用してコマンドパレットを開くことができます。
リポジトリが複製されたら、Visual Studio Code で選択したローカルフォルダーを開きます。

Azure Cosmos DB for NoSQL アカウントを作成する

Azure Cosmos DB は、複数の API をサポートするクラウドベースの NoSQL データベースサービスです。 Azure Cosmos DB アカウントを初めてプロビジョニングするときに、そのアカウントでサポートする API (たとえば、Mongo API や NoSQL API) を選択します。 Azure Cosmos DB for NoSQL アカウントのプロビジョニングが完了したら、エンドポイントとキーを取得し、Azure SDK for .NET または任意の他の SDK を使用して Azure Cosmos DB for NoSQL アカウントに接続する際に使用できます。

新しい Web ブラウザーウィンドウまたはタブで、Azure portal (portal.azure.com) に移動します。
ご利用のサブスクリプションに関連付けられている Microsoft 資格情報を使用して、ポータルにサインインします。

[+ リソースの作成] を選択し、Cosmos DB を検索して、新しい Azure Cosmos DB for NoSQL アカウントリソースを作成します。以下を設定して、残りの設定はすべて既定値のままにします。

設定	Value
サブスクリプション	’‘既存の Azure サブスクリプション’’
リソースグループ	’‘既存のリソースグループを選択するか、新しいものを作成します’’
アカウント名	’‘グローバルに一意の名前を入力します’’
場所	’‘使用可能なリージョンを選びます’’
容量モード	プロビジョニング済みスループット
Apply Free Tier Discount (Free レベル割引の適用)	適用しない

📝 ご利用のラボ環境には、新しいリソースグループを作成できない制限が存在する場合があります。その場合は、事前に作成されている既存のリソースグループを使用します。

デプロイタスクが完了するまで待ってから、このタスクを続行してください。
新しく作成された Azure Cosmos DB アカウントリソースに移動し、 [キー] ペインに移動します。
このペインには、SDK からアカウントに接続するために必要な接続の詳細と資格情報が含まれています。具体的な内容は次のとおりです。
1. [URI] フィールドに注目します。このエンドポイントの値は、この演習で後ほど使用します。
2. [主キー] フィールドに注目してください。このキーの値は、この演習で後ほど使用します。
ブラウザーウィンドウを閉じずに、Visual Studio Code を開きます。

Azure Cosmos DB for NoSQL アカウントにデータをシードする

cosmicworks コマンドラインツールを使用して、Azure Cosmos DB for NoSQL アカウントにサンプルデータをデプロイします。このツールはオープンソースで、NuGet から入手できます。このツールを Azure Cloud Shell にインストールして、データベースのシードに使用します。

Visual Studio Code で、 [ターミナル] メニューを開き、 [新しいターミナル] を選択して新しいターミナルインスタンスを開きます。
コンピューターでグローバルに使用するために cosmicworks コマンドラインツールをインストールします。
```
 dotnet tool install cosmicworks --global --version 1.*
```
💡 このコマンドが完了するまで数分かかる場合があります。過去にこのツールの最新バージョンを既にインストールしている場合は、このコマンドによって警告メッセージ (*ツール ‘cosmicworks’ は既にインストールされています) が出力されます。

cosmicworks を実行し、次のコマンドラインオプションを使用して Azure Cosmos DB アカウントをシードします。

オプション	Value
–endpoint	’‘このラボで先ほどコピーしたエンドポイントの値’’
–key	’‘このラボで先ほどコピーしたキーの値’’
–datasets	product

 cosmicworks --endpoint <cosmos-endpoint> --key <cosmos-key> --datasets product

📝 たとえば、エンドポイントが https://dp420.documents.azure.com:443/ で、キーが fDR2ci9QgkdkvERTQ== の場合、コマンドは次のようになります。cosmicworks --endpoint https://dp420.documents.azure.com:443/ --key fDR2ci9QgkdkvERTQ== --datasets product

cosmicworks コマンドによって、データベース、コンテナー、および項目がアカウントに設定されるまで待ちます。
統合ターミナルを閉じます。

.NET SDK を使用してユーザー定義関数 (UDF) を作成する

.NET SDK の Container クラスには、SDK から直接ストアドプロシージャ、UDF、およびトリガーに対して CRUD 操作を実行するために使用する Scripts プロパティが用意されています。このプロパティを使用して、新しい UDF を作成し、その UDF を Azure Cosmos DB for NoSQL コンテナーにプッシュします。 UDF を SDK を使用して作成すると、製品の税込み価格が計算され、税込み価格を使用して製品で SQL クエリを実行できるようになります。

Visual Studio Code の [エクスプローラー] ペインで、33-create-use-udf-sdk フォルダーを参照します。
script.cs コードファイルを開きます。
Microsoft.Azure.Cosmos.Scripts 名前空間の using ブロックを追加します。
```
 using Microsoft.Azure.Cosmos.Scripts;
```
endpoint という名前の既存の変数を、先ほど作成した Azure Cosmos DB アカウントの endpoint に設定された値で更新します。
```
 string endpoint = "<cosmos-endpoint>";
```
📝 たとえば、ご自分のエンドポイントが https://dp420.documents.azure.com:443/ の場合、C# ステートメントは string endpoint = “https://dp420.documents.azure.com:443/”; になります。
key という名前の既存の変数を、先ほど作成した Azure Cosmos DB アカウントの key に設定された値で更新します。
```
 string key = "<cosmos-key>";
```
📝 たとえば、キーが fDR2ci9QgkdkvERTQ== の場合、C# ステートメントは string key = “fDR2ci9QgkdkvERTQ==”; になります。
既定の空のコンストラクターを使用して、props という名前の UserDefinedFunctionProperties 型の新しい変数を作成します。
```
 UserDefinedFunctionProperties props = new ();
```
props 変数の Id プロパティを tax の値に設定します。
```
 props.Id = "tax";
```
props 変数の Body プロパティを props.Body = “function tax(i) { return i * 1.25; }”; に設定します。
```
 props.Body = "function tax(i) { return i * 1.25; }";
```
パラメーターとして props 変数を渡して、container 変数の Scripts.CreateUserDefinedFunctionAsync メソッドを非同期に呼び出し、結果を UserDefinedFunctionResponse 型の udf という名前の変数に保存します。
```
 UserDefinedFunctionResponse udf = await container.Scripts.CreateUserDefinedFunctionAsync(props);
```
組み込みの Console.WriteLine 静的メソッドを使用して、Created UDF というタイトルのヘッダーを持つ UserDefinedFunctionResponse クラスの Resource.Id プロパティを出力します。
```
 Console.WriteLine($"Created UDF [{udf.Resource?.Id}]");
```

完了すると、コードファイルが次のようになるはずです。

 using System;
 using Microsoft.Azure.Cosmos;
 using Microsoft.Azure.Cosmos.Scripts;

 string endpoint = "<cosmos-endpoint>";

 string key = "<cosmos-key>";

 CosmosClient client = new CosmosClient(endpoint, key);

 Database database = await client.CreateDatabaseIfNotExistsAsync("cosmicworks");

 Container container = await database.CreateContainerIfNotExistsAsync("products", "/categoryId");

 UserDefinedFunctionProperties props = new ();
 props.Id = "tax";
 props.Body = "function tax(i) { return i * 1.25; }";
    
 UserDefinedFunctionResponse udf = await container.Scripts.CreateUserDefinedFunctionAsync(props);
    
 Console.WriteLine($"Created UDF [{udf.Resource?.Id}]");

script.cs ファイルを保存します。
Visual Studio Code で、33-create-use-udf-sdk フォルダーのコンテキストメニューを開き、[統合ターミナルで開く] を選択して新しいターミナルインスタンスを開きます。
dotnet run コマンドを使用して、プロジェクトをビルドして実行します。
```
 dotnet run
```
スクリプトにより、新しく作成した UDF の名前が出力されます。
```
 Created UDF [tax]
```
統合ターミナルを閉じます。
Visual Studio Code を閉じます。

データエクスプローラーを使用して UDF をテストする

Azure Cosmos DB コンテナーに新しい UDF を作成したので、データエクスプローラーを使用して UDF が想定どおりに動作していることを検証します。