Azure Logic Apps を使用した Azure Cosmos DB ドキュメントの処理および作成
適用対象: Azure Logic Apps (従量課金プラン + Standard)
Azure Logic Apps のワークフローから Azure Cosmos DB に接続し、Azure Cosmos DB コネクタを使用してドキュメントを操作できます。 このコネクタは、ワークフローが Azure Cosmos DB の操作に使用できるトリガーとアクションを提供します。 たとえば、アクションには、ドキュメントの作成または更新、読み取り、照会、削除が含まれます。
Azure Cosmos DB には、"マネージド コネクタ" を操作することにより、ロジック アプリ (従量課金) およびロジック アプリ (Standard) の両方の種類のリソースから接続することができます。 ロジック アプリ (Standard) の場合、Azure Cosmos DB の "組み込み" 操作も提供されています。これは現在プレビュー段階ですが、さまざまな機能があり、パフォーマンスとスループットが向上しています。 たとえば、ロジック アプリ (Standard) リソースの種類を使用している場合は、組み込みのトリガーを使用して、Azure Cosmos DB コンテナーの変更に応答できます。 ロジック アプリ ワークフロー内の他のアクションやトリガーと Azure Cosmos DB 操作を組み合わせることで、イベント ソーシングや一般的なデータ処理などのシナリオを実現できます。
制限事項
現在、マネージド コネクタ操作と組み込み操作の両方を使用できるのは、ロジック アプリ (Standard) リソース内のステートフル ワークフローだけです。 ステートレス ワークフローで使用できるのは、組み込み操作のみです。
Azure Cosmos DB コネクタでは、Azure Cosmos DB for NoSQL で作成された Azure Cosmos DB アカウントのみがサポートされます。
前提条件
Azure アカウントとサブスクリプション。 Azure サブスクリプションがない場合は、無料の Azure アカウントにサインアップしてください。
自分の Azure Cosmos DB アカウントにアクセスするロジック アプリ ワークフロー。 Azure Cosmos DB トリガーを使用するには、ロジック アプリ (Standard) のリソースの種類を使用してロジック アプリを作成し、空のワークフローを追加する必要があります。
Azure Cosmos DB のトリガーの追加
Azure Logic Apps では、すべてのワークフローは、必ずトリガーで開始します。トリガーは、特定のイベントが起こるか特定の条件が満たされたときに発生します。
ロジック アプリ (Standard) のリソースの種類を使用している場合、Azure Cosmos DB の変更フィード パターンに基づく [アイテムが作成または変更されたとき] (プレビュー) という組み込みのトリガーを使用することができます。 このトリガーは、ロジックアプリ (従量課金) のリソースの種類では使用できません。
![[アイテムが作成または変更されたとき] (プレビュー) というトリガーが選択されている Standard ロジック アプリ ワークフローを示す Azure portal とデザイナーのスクリーンショット。](media/connectors-create-api-cosmos-db/standard-trigger-add.png)
Azure Cosmos DB のアクションの追加
Azure Logic Apps では、アクションとは、トリガーまたは別のアクションに続くワークフロー内のステップです。 Azure Cosmos DB コネクタでは、ロジックアプリ (従量課金) とロジック アプリ (Standard) の両方のリソースの種類向けにアクションが提供されています。 次の例は、各リソースの種類でアクションを使用し、ドキュメントを作成または更新する方法を示しています。
マルチテナントの Azure Logic Apps で、ロジック アプリ ワークフローに Azure Cosmos DB のアクションを追加するには、次の手順を実行します。
Azure portal で、ワークフローをデザイナーで開きます。
ワークフローが空の場合は、任意のトリガーを追加します。
この例は、[HTTP 要求の受信時] というトリガーで始まります。
Azure Cosmos DB のアクションを追加するトリガーまたはアクションの下にある [新しいステップ] または [アクションの追加] (ステップの途中の場合) を選択します。
デザイナーの検索ボックスに、「
Azure Cosmos DB」と入力します。 使用する Azure Cosmos DB アクションの種類を選択します。この例では、[ドキュメントを作成または更新する (V3)] という名前のアクションを使用します。
接続の詳細の入力を求められたら、自分の Azure Cosmos DB アカウントへの接続を作成します。
アクションに必要な情報を指定します。
プロパティ 必要 値 説明 Azure Cosmos DB アカウント名 はい [接続設定を使用する](<Azure-Cosmos-DB-account-name>) を選ぶか、名前を手動で入力します。 Azure Cosmos DB アカウントのアカウント名。 データベース ID はい <database-ID> 接続先のデータベース。 コンテナー ID はい <container-ID> 照会先のコンテナー。 ドキュメント はい "<JSON ドキュメント>" 作成する JSON ドキュメント。 この例では、トリガー出力からの要求本文を使用します。 ヒント: HTTP トリガーの本文トークンが、追加する動的なコンテンツの一覧に表示されない場合は、トリガー名の横にある [さらに表示] を選択します。
注: 本文が適切な形式の JSON であることを確認してください。少なくとも、ドキュメントに
idプロパティとパーティション キーのプロパティが含まれていることを確認してください。 指定したidとパーティション キーを備えたドキュメントが既に存在する場合は、ドキュメントが更新されます。 そうでない場合は、新しいドキュメントが作成されます。次の図にアクションの例を示します。
![Azure Cosmos DB の [ドキュメントを作成または更新する (V3)] アクションとパラメーターの構成が含まれている従量課金のロジック アプリ ワークフローのデザイナーを示すスクリーンショット。](media/connectors-create-api-cosmos-db/consumption-create-action.png)
必要に応じて、他のアクション設定を構成します。
デザイナー ツールバーで、保存を選択します。
ロジック アプリをテストして、ワークフローによってドキュメントが指定されたコンテナーに作成されることを確認します。
![Azure Cosmos DB の [HTTP 要求の受信時] トリガーとパラメーターの構成が含まれている Standard ロジック アプリ ワークフローのデザイナーを示す Azure portal とデザイナーのスクリーンショット。](media/connectors-create-api-cosmos-db/standard-http-trigger.png)
![Azure Cosmos DB の [Create or update item]\(アイテムの作成または更新\) アクションとパラメーター構成を含む、Standard ロジック アプリ ワークフローのデザイナーを示すスクリーンショット。](media/connectors-create-api-cosmos-db/standard-create-action.png)
Azure Cosmos DB への接続
サービスまたはシステムに接続するトリガーまたはアクションを追加しており、既存またはアクティブな接続がない場合、Azure Logic Apps には、接続の種類によって異なる接続情報を提供するように求めるプロンプトが表示されます。次に例を示します。
- アカウントの資格情報
- 接続に使う名前
- サーバーまたはシステムの名前
- 使用する認証の種類
- 接続の文字列
Azure Cosmos DB トリガーまたは Azure Cosmos DB アクションを構成するには、あらかじめデータベース アカウントに接続しておく必要があります。
ロジック アプリ (従量課金) ワークフローの Azure Cosmos DB 接続では、次のプロパティ値が必要です。
| プロパティ | 必要 | 値 | 説明 |
|---|---|---|---|
| 接続名 | はい | <connection-name> | 接続に使用する名前。 |
| 認証の種類 | はい | <connection-type> | 使用する認証の種類。 この例では、[アクセス キー] を使用します。 - [アクセス キー] を選択した場合は、残りの必須プロパティ値を指定して接続を作成します。 - Microsoft Entra 統合 を選択した場合、他のプロパティ値は必要ありませんが、Microsoft Entra 認証と Azure Cosmos DB コネクタ の手順に従って接続を構成する必要があります。 |
| ご利用の Azure Cosmos DB アカウントに対するアクセス キー | はい | "<アクセス キー>" | この接続に使用する Azure Cosmos DB アカウントのアクセス キー。 この値は、読み取り/書き込みキーおよび読み取り専用キーとして使用できます。 注: キーを見つけるには、Azure Cosmos DB アカウント ページに移動します。 ナビゲーション メニューの [設定] で、[キー] を選択します。 使用可能なキー値のいずれかをコピーします。 |
| アカウント ID | はい | "<アカウント ID>" | この接続に使用する Azure Cosmos DB アカウントの名前。 |
次の図に接続の例を示します。
Note
接続を作成した後、代わりに別の既存の Azure Cosmos DB 接続を使用する場合、または別の接続を新規に作成する場合は、トリガーまたはアクションの詳細エディターで [接続の変更] を選択します。
コネクタのリファレンス
トリガー、アクション、制限など、Azure Cosmos DB "マネージド コネクタ" の操作に関する詳細については、コネクタのリファレンス ページを確認してください。
Azure Cosmos DB の "組み込み" 操作に対応するリファレンス ページは存在しません。 代わりに、次の表で詳細を確認してください。
| Type | 名前 | パラメーター |
|---|---|---|
| トリガー | アイテムが作成または修正されたとき | - データベース ID:: 必須。 監視対象のコンテナーとリース コンテナーを含むデータベースの名前。 - 監視対象のコンテナー ID: 必須。 監視対象のコンテナーの名前。 - リース コンテナー ID: 必須。 リースの保存のために使用するコンテナーの名前。 - リース コンテナーの作成: 必須。 true の場合は、リース コンテナーを作成します (まだ存在していない場合)。 - リース コンテナーのスループット: 省略可能。 リース コンテナーの作成時に割り当てる要求ユニットの数。 |
| アクション | Create or update item (アイテムの作成または更新) | - データベース ID:: 必須。 データベースの名前です。 - コンテナー ID: 必須。 コンテナーの名前。 - 項目: 必須。 作成または更新する項目。 - パーティション キー: 省略可能。 要求された項目のパーティション キーの値。 - Is Upsert (アップサート): 省略可能。 true の場合は、項目を置き換えます (存在する場合)。 そうでない場合は、項目を作成します。 |
| アクション | Create or update many items in bulk (多数の項目の一括作成または一括更新) | このアクションは高スループットのシナリオに合わせて最適化されており、Azure Cosmos DB コンテナーで作成される項目がアクションから送信される前に、追加の処理が行われます。 項目数が多い場合、この追加の処理によって総合的な所要時間が短縮されます。 項目数が少ない場合、この追加のオーバーヘッドによって、項目作成のアクションを個別に複数使用する場合よりもパフォーマンスが低下する可能性があります。 - データベース ID:: 必須。 データベースの名前です。 |
| アクション | 項目を読み取る | - データベース ID:: 必須。 データベースの名前です。 - コンテナー ID: 必須。 コンテナーの名前。 - 項目 ID: 必須。 要求された項目の id の値。 - パーティション キー: 必須。 要求された項目のパーティション キーの値。 |
| アクション | 項目を削除する | - データベース ID:: 必須。 データベースの名前です。 - コンテナー ID: 必須。 コンテナーの名前。 - 項目 ID: 必須。 要求された項目の id の値。 - パーティション キー: 必須。 要求された項目のパーティション キーの値。 |
| アクション | クエリ項目 | - データベース ID:: 必須。 データベースの名前です。 - コンテナー ID: 必須。 コンテナーの名前。 - SQL クエリ: 必須。 Azure Cosmos DB の SQL クエリ テキスト。 - パーティション キー: 省略可能。 要求のパーティション キーの値 (存在する場合)。 - 継続トークン: 省略可能。 Azure Cosmos DB サービスによって指定された、このクエリの後続トークン (存在する場合)。 - 最大項目数: 省略可能。 クエリで返す項目の最大数。 |
Azure Cosmos DB 組み込み操作のベスト プラクティス
[Query items]\(クエリ項目\) アクションから反復処理できる結果を取得する
Logic App (Standard) ワークフローに組み込まれた [Query items]\(クエリ項目\) アクションには、後続のアクションで使用できる多くの動的コンテンツの出力があります。 クエリ結果項目または項目のメタデータを反復処理できるオブジェクトとして取得するには、次のステップを使います。
Azure portal で、ワークフローをデザイナーで開きます。
ワークフローが空の場合は、任意のトリガーを追加します。
この例は、[繰り返し] トリガーで始まります。
Azure Cosmos DB アクションを追加するトリガーまたはアクションの下にある [新しいステップの挿入] (+) > [アクションの追加] を選びます。
デザイナーで、[操作の追加] が選択されていることを確認してください。 [アクションの追加] ペインが開いたら、[操作を選択してください] 検索ボックスで [ビルトイン] を選択し、Azure Cosmos DB のアクションを見つけます。
検索ボックスに「
Azure Cosmos DB」と入力します。 [Query items (preview)]\(項目のクエリ (プレビュー)\) アクションを選択します。接続の詳細の入力を求められたら、自分の Azure Cosmos DB アカウントへの接続を作成します。
アクションに必要な情報を指定します。
プロパティ 必須 値 説明 データベース ID はい <database-ID> 接続先のデータベース。 コンテナー ID はい <container-ID> 照会先のコンテナー。 SQL クエリ はい "<SQL クエリ>" 使用する要求の SQL クエリ。 次の図にアクションの例を示します。
![Azure Cosmos DB の [Query items]\(項目のクエリ\) アクションとパラメーター構成を含む、Standard ロジック アプリ ワークフローのデザイナーを示すスクリーンショット。](media/connectors-create-api-cosmos-db/standard-query-action.png)
必要に応じて、他のアクション設定を構成します。
アクションの下にある [新しいステップの挿入] (+) >[アクションの追加] を選びます。 開いた [アクションの追加] ペインで、すべてのクエリ結果項目に対して実行するアクションを選びます。
この例では、Azure Cosmos DB の組み込みアクションである [Delete an item (preview)]\(項目の削除 (プレビュー)\) を使います。
- 先ほど追加したアクションでは、クエリ アクションの出力からデータにアクセスできます。 そのアクションのいずれかの入力フィールド内をクリックすると、動的コンテンツ一覧が表示されます。 使用できる応答項目のいずれかを選ぶか、[詳細表示] を選んで他のオプションを表示します。
この例では、[項目 ID] フィールドの [Response Item Id]\(応答項目 ID\) を使い、クエリ結果に基づいて ID を入力しています。
![Azure Cosmos DB **[Query items]\(クエリ項目\)** アクションの動的コンテンツ出力を使った Standard ロジック アプリ ワークフローのデザイナーを示すスクリーンショット。](media/connectors-create-api-cosmos-db/standard-query-output.png)
応答項目を選ぶと、すべてのクエリ結果を反復処理する For each アクションが自動的に追加されます。 For each ループには、先ほど追加したアクションが含まれています。 ループには、他にも必要なアクションを追加することができます。
デザイナー ツールバーで、保存を選択します。
ロジック アプリをテストして、予想どおりの出力がワークフローから返されることを確認します。