Azure Functions 2.x 以降に対する Azure Cosmos DB の入力バインド
Azure Cosmos DB 入力バインドでは、SQL API を使用して 1 つ以上の Azure Cosmos DB ドキュメントを取得して関数の入力パラメーターに渡します。 ドキュメント ID またはクエリ パラメーターは、関数を呼び出したトリガーに基づいて決定することができます。
セットアップと構成の詳細については、概要に関するページをご覧ください。
Note
コレクションがパーティション分割されている場合、検索操作では、パーティション キーの値も指定する必要があります。
重要
この記事では、タブを使って、Node.js プログラミング モデルの複数のバージョンをサポートします。 v4 モデルは現在プレビュー段階で、JavaScript と TypeScript の開発者にとって、より柔軟で直感的なエクスペリエンスが得られるように設計されています。 v3 と v4 の違いの詳細については、アップグレード ガイドを参照してください。
Azure Functions では、Python の 2 つのプログラミング モデルがサポートされています。 バインドを定義する方法は、選択したプログラミング モデルによって異なります。
Python v2 プログラミング モデルでは、Python 関数コードでデコレーターを使用してバインドを直接定義できます。 詳細については、「Python 開発者ガイド」を参照してください。
この記事は、両方のプログラミング モデルをサポートしています。
例
特に記載がない限り、この記事の例は Azure Cosmos DB 拡張機能のバージョン 3.x を対象としています。 拡張機能バージョン 4.x で使用するには、プロパティ名や属性名の文字列 collection を container に置き換える必要があります。
A C# 関数は、次の C# モードのいずれかを使用して作成できます。
- インプロセス クラス ライブラリ: Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数。 このモデルの一部では、主に C# ポータルの編集のためにサポートされている C# スクリプトを使用して Functions を実行できます。 インプロセス関数の拡張機能では、
Microsoft.Azure.WebJobs.Extensions.*名前空間が使用されます。 - 分離ワーカー プロセス クラス ライブラリ: ランタイムから分離されたワーカー プロセスで実行されるコンパイル済みの C# 関数。 分離ワーカー プロセスは、LTS および 非 LTS バージョンの .NET および .NET Framework で実行されている C# 関数をサポートするために必要です。 分離ワーカー プロセス関数の拡張機能では、
Microsoft.Azure.Functions.Worker.Extensions.*名前空間が使用されます。
このセクションには、拡張バージョン3.x でインプロセス C# クラス ライブラリ関数を使用するための次の例が含まれています。
- キュー トリガー、JSON からの ID の検索
- HTTP トリガー、クエリ文字列からの ID の検索
- HTTP トリガー、ルート データからの ID の検索
- HTTP トリガー、SqlQuery を使用したルート データからの ID の検索
- HTTP トリガー、SqlQuery を使用した複数のドキュメントの取得
- HTTP トリガー、DocumentClient を使用した複数のドキュメントの取得
- HTTP トリガー、CosmosClient (v4 拡張機能) を使用した複数のドキュメントの取得
例では、次のようなシンプルな ToDoItem タイプを参照します。
namespace CosmosDBSamplesV2
{
public class ToDoItem
{
[JsonProperty("id")]
public string Id { get; set; }
[JsonProperty("partitionKey")]
public string PartitionKey { get; set; }
public string Description { get; set; }
}
}
キュー トリガー、JSON からの ID の検索
次の例は、単一のドキュメントを取得する C# 関数を示しています。 関数は、JSON オブジェクトを含むキュー メッセージによってトリガーされます。 キュー トリガーにより、検索する ID とパーティション キー値を含む、ToDoItemLookup タイプのオブジェクトに JSON が解析されます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
namespace CosmosDBSamplesV2
{
public class ToDoItemLookup
{
public string ToDoItemId { get; set; }
public string ToDoItemPartitionKeyValue { get; set; }
}
}
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
namespace CosmosDBSamplesV2
{
public static class DocByIdFromJSON
{
[FunctionName("DocByIdFromJSON")]
public static void Run(
[QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
[CosmosDB(
databaseName: "ToDoItems",
collectionName: "Items",
ConnectionStringSetting = "CosmosDBConnection",
Id = "{ToDoItemId}",
PartitionKey = "{ToDoItemPartitionKeyValue}")]ToDoItem toDoItem,
ILogger log)
{
log.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");
if (toDoItem == null)
{
log.LogInformation($"ToDo item not found");
}
else
{
log.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
}
}
}
}
HTTP トリガー、クエリ文字列からの ID の検索
次の例は、単一のドキュメントを取得する C# 関数を示しています。 関数は、クエリ文字列を使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
Note
HTTP クエリ文字列パラメーターは大文字と小文字が区別されます。
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
namespace CosmosDBSamplesV2
{
public static class DocByIdFromQueryString
{
[FunctionName("DocByIdFromQueryString")]
public static IActionResult Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
HttpRequest req,
[CosmosDB(
databaseName: "ToDoItems",
collectionName: "Items",
ConnectionStringSetting = "CosmosDBConnection",
Id = "{Query.id}",
PartitionKey = "{Query.partitionKey}")] ToDoItem toDoItem,
ILogger log)
{
log.LogInformation("C# HTTP trigger function processed a request.");
if (toDoItem == null)
{
log.LogInformation($"ToDo item not found");
}
else
{
log.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
}
return new OkResult();
}
}
}
HTTP トリガー、ルート データからの ID の検索
次の例は、単一のドキュメントを取得する C# 関数を示しています。 関数は、ルート データを使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
namespace CosmosDBSamplesV2
{
public static class DocByIdFromRouteData
{
[FunctionName("DocByIdFromRouteData")]
public static IActionResult Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
Route = "todoitems/{partitionKey}/{id}")]HttpRequest req,
[CosmosDB(
databaseName: "ToDoItems",
collectionName: "Items",
ConnectionStringSetting = "CosmosDBConnection",
Id = "{id}",
PartitionKey = "{partitionKey}")] ToDoItem toDoItem,
ILogger log)
{
log.LogInformation("C# HTTP trigger function processed a request.");
if (toDoItem == null)
{
log.LogInformation($"ToDo item not found");
}
else
{
log.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
}
return new OkResult();
}
}
}
HTTP トリガー、SqlQuery を使用したルート データからの ID の検索
次の例は、単一のドキュメントを取得する C# 関数を示しています。 関数は、ルート データを使用して検索のための ID を指定する HTTP 要求によってトリガーされます。 該当の ID は、指定されたデータベースとコレクションからの ToDoItem ドキュメントの取得に使用されます。
例では、SqlQuery パラメーターでバインド式を使用する方法を示しています。 ここに示したようにルート データを SqlQuery パラメーターに渡すことはできますが、現在、クエリ文字列の値を渡すことはできません。
Note
ID だけでクエリを実行する必要がある場合、前の例のように、参照を使用することをお勧めします。要求ユニットの消費が少なくなります。 ポイント読み取り操作 (GET) は ID によるクエリより効率性に優れています。
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;
namespace CosmosDBSamplesV2
{
public static class DocByIdFromRouteDataUsingSqlQuery
{
[FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
public static IActionResult Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
Route = "todoitems2/{id}")]HttpRequest req,
[CosmosDB("ToDoItems", "Items",
ConnectionStringSetting = "CosmosDBConnection",
SqlQuery = "select * from ToDoItems r where r.id = {id}")]
IEnumerable<ToDoItem> toDoItems,
ILogger log)
{
log.LogInformation("C# HTTP trigger function processed a request.");
foreach (ToDoItem toDoItem in toDoItems)
{
log.LogInformation(toDoItem.Description);
}
return new OkResult();
}
}
}
HTTP トリガー、SqlQuery を使用した複数のドキュメントの取得
次の例は、ドキュメントの一覧を取得する C# 関数を示しています。 関数は、HTTP 要求によってトリガーされます。 クエリは、SqlQuery 属性プロパティで指定されます。
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;
namespace CosmosDBSamplesV2
{
public static class DocsBySqlQuery
{
[FunctionName("DocsBySqlQuery")]
public static IActionResult Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
HttpRequest req,
[CosmosDB(
databaseName: "ToDoItems",
collectionName: "Items",
ConnectionStringSetting = "CosmosDBConnection",
SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
IEnumerable<ToDoItem> toDoItems,
ILogger log)
{
log.LogInformation("C# HTTP trigger function processed a request.");
foreach (ToDoItem toDoItem in toDoItems)
{
log.LogInformation(toDoItem.Description);
}
return new OkResult();
}
}
}
HTTP トリガー、DocumentClient を使用した複数のドキュメントの取得
次の例は、ドキュメントの一覧を取得する C# 関数を示しています。 関数は、HTTP 要求によってトリガーされます。 コードでは、Azure Cosmos DB バインドによって提供される DocumentClient インスタンスを使用して、ドキュメントの一覧を読み取ります。 また、DocumentClient インスタンスは、書き込み操作に使用できます。
Note
IDocumentClient インターフェイスを使用してテストを容易にすることもできます。
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;
using System.Linq;
using System.Threading.Tasks;
namespace CosmosDBSamplesV2
{
public static class DocsByUsingDocumentClient
{
[FunctionName("DocsByUsingDocumentClient")]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
Route = null)]HttpRequest req,
[CosmosDB(
databaseName: "ToDoItems",
collectionName: "Items",
ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
ILogger log)
{
log.LogInformation("C# HTTP trigger function processed a request.");
var searchterm = req.Query["searchterm"];
if (string.IsNullOrWhiteSpace(searchterm))
{
return (ActionResult)new NotFoundResult();
}
Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");
log.LogInformation($"Searching for: {searchterm}");
IDocumentQuery<ToDoItem> query = client.CreateDocumentQuery<ToDoItem>(collectionUri)
.Where(p => p.Description.Contains(searchterm))
.AsDocumentQuery();
while (query.HasMoreResults)
{
foreach (ToDoItem result in await query.ExecuteNextAsync())
{
log.LogInformation(result.Description);
}
}
return new OkResult();
}
}
}
HTTP トリガー、CosmosClient を使用した複数のドキュメントの取得
次の例は、ドキュメントの一覧を取得する C# 関数を示しています。 関数は、HTTP 要求によってトリガーされます。 コードでは、拡張機能バージョン 4.x で使用可能な Azure Cosmos DB バインドによって提供される CosmosClient インスタンスを使用して、ドキュメントの一覧を読み取ります。 また、CosmosClient インスタンスは、書き込み操作に使用できます。
using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;
namespace CosmosDBSamplesV2
{
public static class DocsByUsingCosmosClient
{
[FunctionName("DocsByUsingCosmosClient")]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
Route = null)]HttpRequest req,
[CosmosDB(
databaseName: "ToDoItems",
containerName: "Items",
Connection = "CosmosDBConnection")] CosmosClient client,
ILogger log)
{
log.LogInformation("C# HTTP trigger function processed a request.");
var searchterm = req.Query["searchterm"].ToString();
if (string.IsNullOrWhiteSpace(searchterm))
{
return (ActionResult)new NotFoundResult();
}
Container container = client.GetDatabase("ToDoItems").GetContainer("Items");
log.LogInformation($"Searching for: {searchterm}");
QueryDefinition queryDefinition = new QueryDefinition(
"SELECT * FROM items i WHERE CONTAINS(i.Description, @searchterm)")
.WithParameter("@searchterm", searchterm);
using (FeedIterator<ToDoItem> resultSet = container.GetItemQueryIterator<ToDoItem>(queryDefinition))
{
while (resultSet.HasMoreResults)
{
FeedResponse<ToDoItem> response = await resultSet.ReadNextAsync();
ToDoItem item = response.First();
log.LogInformation(item.Description);
}
}
return new OkResult();
}
}
}
このセクションには、次の例が含まれています。
- HTTP トリガー、クエリ文字列からの ID の検索 - String パラメーター
- HTTP トリガー、クエリ文字列からの ID の検索 - POJO パラメーター
- HTTP トリガー、ルート データからの ID の検索
- HTTP トリガー、SqlQuery を使用したルート データからの ID の検索
- HTTP トリガー、ルート データからの複数のドキュメントの取得、SqlQuery を使用
例では、次のようなシンプルな ToDoItem タイプを参照します。
public class ToDoItem {
private String id;
private String description;
public String getId() {
return id;
}
public String getDescription() {
return description;
}
@Override
public String toString() {
return "ToDoItem={id=" + id + ",description=" + description + "}";
}
}
HTTP トリガー、クエリ文字列からの ID の検索 - String パラメーター
次の例は、単一のドキュメントを取得する Java 関数を示しています。 関数は、クエリ文字列を使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションからドキュメントを String 形式で取得するために使用されます。
public class DocByIdFromQueryString {
@FunctionName("DocByIdFromQueryString")
public HttpResponseMessage run(
@HttpTrigger(name = "req",
methods = {HttpMethod.GET, HttpMethod.POST},
authLevel = AuthorizationLevel.ANONYMOUS)
HttpRequestMessage<Optional<String>> request,
@CosmosDBInput(name = "database",
databaseName = "ToDoList",
collectionName = "Items",
id = "{Query.id}",
partitionKey = "{Query.partitionKeyValue}",
connectionStringSetting = "Cosmos_DB_Connection_String")
Optional<String> item,
final ExecutionContext context) {
// Item list
context.getLogger().info("Parameters are: " + request.getQueryParameters());
context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));
// Convert and display
if (!item.isPresent()) {
return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
.body("Document not found.")
.build();
}
else {
// return JSON from Cosmos. Alternatively, we can parse the JSON string
// and return an enriched JSON object.
return request.createResponseBuilder(HttpStatus.OK)
.header("Content-Type", "application/json")
.body(item.get())
.build();
}
}
}
Java 関数ランタイム ライブラリで、その値が Azure Cosmos DB に由来する関数パラメーター上で @CosmosDBInput 注釈を使用します。 この注釈は、Java のネイティブ型、POJO、または Optional<T> を使用した null 許容値で使用できます。
HTTP トリガー、クエリ文字列からの ID の検索 - POJO パラメーター
次の例は、単一のドキュメントを取得する Java 関数を示しています。 関数は、クエリ文字列を使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションからドキュメントを取得するために使用されます。 このドキュメントはその後、前に作成した ToDoItem POJO のインスタンスに変換され、引数として関数に渡されます。
public class DocByIdFromQueryStringPojo {
@FunctionName("DocByIdFromQueryStringPojo")
public HttpResponseMessage run(
@HttpTrigger(name = "req",
methods = {HttpMethod.GET, HttpMethod.POST},
authLevel = AuthorizationLevel.ANONYMOUS)
HttpRequestMessage<Optional<String>> request,
@CosmosDBInput(name = "database",
databaseName = "ToDoList",
collectionName = "Items",
id = "{Query.id}",
partitionKey = "{Query.partitionKeyValue}",
connectionStringSetting = "Cosmos_DB_Connection_String")
ToDoItem item,
final ExecutionContext context) {
// Item list
context.getLogger().info("Parameters are: " + request.getQueryParameters());
context.getLogger().info("Item from the database is " + item);
// Convert and display
if (item == null) {
return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
.body("Document not found.")
.build();
}
else {
return request.createResponseBuilder(HttpStatus.OK)
.header("Content-Type", "application/json")
.body(item)
.build();
}
}
}
HTTP トリガー、ルート データからの ID の検索
次の例は、単一のドキュメントを取得する Java 関数を示しています。 関数は、ルート パラメーターを使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションからドキュメントを取得し、Optional<String> として返すために使用されます。
public class DocByIdFromRoute {
@FunctionName("DocByIdFromRoute")
public HttpResponseMessage run(
@HttpTrigger(name = "req",
methods = {HttpMethod.GET, HttpMethod.POST},
authLevel = AuthorizationLevel.ANONYMOUS,
route = "todoitems/{partitionKeyValue}/{id}")
HttpRequestMessage<Optional<String>> request,
@CosmosDBInput(name = "database",
databaseName = "ToDoList",
collectionName = "Items",
id = "{id}",
partitionKey = "{partitionKeyValue}",
connectionStringSetting = "Cosmos_DB_Connection_String")
Optional<String> item,
final ExecutionContext context) {
// Item list
context.getLogger().info("Parameters are: " + request.getQueryParameters());
context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));
// Convert and display
if (!item.isPresent()) {
return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
.body("Document not found.")
.build();
}
else {
// return JSON from Cosmos. Alternatively, we can parse the JSON string
// and return an enriched JSON object.
return request.createResponseBuilder(HttpStatus.OK)
.header("Content-Type", "application/json")
.body(item.get())
.build();
}
}
}
HTTP トリガー、SqlQuery を使用したルート データからの ID の検索
次の例は、単一のドキュメントを取得する Java 関数を示しています。 この関数は、ルート パラメーターを使用して検索する ID を指定する HTTP 要求によってトリガーされます。 クエリ条件によっては多数のドキュメントが返される可能性があるため、その ID は、指定されたデータベースとコレクションからドキュメントを取得し、結果セットを ToDoItem[] に変換するために使用されます。
Note
ID だけでクエリを実行する必要がある場合、前の例のように、参照を使用することをお勧めします。要求ユニットの消費が少なくなります。 ポイント読み取り操作 (GET) は ID によるクエリより効率性に優れています。
public class DocByIdFromRouteSqlQuery {
@FunctionName("DocByIdFromRouteSqlQuery")
public HttpResponseMessage run(
@HttpTrigger(name = "req",
methods = {HttpMethod.GET, HttpMethod.POST},
authLevel = AuthorizationLevel.ANONYMOUS,
route = "todoitems2/{id}")
HttpRequestMessage<Optional<String>> request,
@CosmosDBInput(name = "database",
databaseName = "ToDoList",
collectionName = "Items",
sqlQuery = "select * from Items r where r.id = {id}",
connectionStringSetting = "Cosmos_DB_Connection_String")
ToDoItem[] item,
final ExecutionContext context) {
// Item list
context.getLogger().info("Parameters are: " + request.getQueryParameters());
context.getLogger().info("Items from the database are " + item);
// Convert and display
if (item == null) {
return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
.body("Document not found.")
.build();
}
else {
return request.createResponseBuilder(HttpStatus.OK)
.header("Content-Type", "application/json")
.body(item)
.build();
}
}
}
HTTP トリガー、ルート データからの複数のドキュメントの取得、SqlQuery を使用
次の例は、複数のドキュメントを取得する Java 関数を示しています。 この関数は、ルート パラメーター desc を使用して description フィールドで検索する文字列を指定する HTTP 要求によってトリガーされます。 この検索用語は、指定されたデータベースとコレクションからドキュメントのコレクションを取得し、結果セットを ToDoItem[] に変換して、それを引数として関数に渡すために使用されます。
public class DocsFromRouteSqlQuery {
@FunctionName("DocsFromRouteSqlQuery")
public HttpResponseMessage run(
@HttpTrigger(name = "req",
methods = {HttpMethod.GET},
authLevel = AuthorizationLevel.ANONYMOUS,
route = "todoitems3/{desc}")
HttpRequestMessage<Optional<String>> request,
@CosmosDBInput(name = "database",
databaseName = "ToDoList",
collectionName = "Items",
sqlQuery = "select * from Items r where contains(r.description, {desc})",
connectionStringSetting = "Cosmos_DB_Connection_String")
ToDoItem[] items,
final ExecutionContext context) {
// Item list
context.getLogger().info("Parameters are: " + request.getQueryParameters());
context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));
// Convert and display
if (items == null) {
return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
.body("No documents found.")
.build();
}
else {
return request.createResponseBuilder(HttpStatus.OK)
.header("Content-Type", "application/json")
.body(items)
.build();
}
}
}
このセクションには、次の例が含まれています。各例では、さまざまなソースから ID 値を指定して単一のドキュメントを読み取ります。
- キュー トリガー、JSON からの ID の検索
- HTTP トリガー、クエリ文字列からの ID の検索
- HTTP トリガー、ルート データからの ID の検索
- キュー トリガー、SqlQuery を使用した複数のドキュメントの取得
キュー トリガー、JSON からの ID の検索
次の例は、単一のドキュメントを読み取り、そのドキュメントのテキスト値を更新する TypeScript 関数を示しています。
import { app, input, InvocationContext, output } from '@azure/functions';
const cosmosInput = input.cosmosDB({
databaseName: 'MyDatabase',
collectionName: 'MyCollection',
id: '{queueTrigger}',
partitionKey: '{queueTrigger}',
connectionStringSetting: 'MyAccount_COSMOSDB',
});
const cosmosOutput = output.cosmosDB({
databaseName: 'MyDatabase',
collectionName: 'MyCollection',
createIfNotExists: false,
partitionKey: '{queueTrigger}',
connectionStringSetting: 'MyAccount_COSMOSDB',
});
interface MyDocument {
text: string;
}
export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
const doc = <MyDocument>context.extraInputs.get(cosmosInput);
doc.text = 'This was updated!';
context.extraOutputs.set(cosmosOutput, doc);
}
app.storageQueue('storageQueueTrigger1', {
queueName: 'outqueue',
connection: 'MyStorageConnectionAppSetting',
extraInputs: [cosmosInput],
extraOutputs: [cosmosOutput],
handler: storageQueueTrigger1,
});
HTTP トリガー、クエリ文字列からの ID の検索
次の例は、単一のドキュメントを取得する TypeScript 関数を示しています。 関数は、クエリ文字列を使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';
const cosmosInput = input.cosmosDB({
databaseName: 'ToDoItems',
collectionName: 'Items',
id: '{Query.id}',
partitionKey: '{Query.partitionKeyValue}',
connectionStringSetting: 'CosmosDBConnection',
});
interface ToDoDocument {
description: string;
}
export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
if (!toDoItem) {
return {
status: 404,
body: 'ToDo item not found',
};
} else {
return {
body: `Found ToDo item, Description=${toDoItem.description}`,
};
}
}
app.http('httpTrigger1', {
methods: ['GET', 'POST'],
authLevel: 'anonymous',
extraInputs: [cosmosInput],
handler: httpTrigger1,
});
HTTP トリガー、ルート データからの ID の検索
次の例は、単一のドキュメントを取得する TypeScript 関数を示しています。 関数は、ルート データを使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
import { app, HttpRequest, HttpResponseInit, input, InvocationContext } from '@azure/functions';
const cosmosInput = input.cosmosDB({
databaseName: 'ToDoItems',
collectionName: 'Items',
id: '{id}',
partitionKey: '{partitionKeyValue}',
connectionStringSetting: 'CosmosDBConnection',
});
interface ToDoDocument {
description: string;
}
export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
if (!toDoItem) {
return {
status: 404,
body: 'ToDo item not found',
};
} else {
return {
body: `Found ToDo item, Description=${toDoItem.description}`,
};
}
}
app.http('httpTrigger1', {
methods: ['GET', 'POST'],
authLevel: 'anonymous',
route: 'todoitems/{partitionKeyValue}/{id}',
extraInputs: [cosmosInput],
handler: httpTrigger1,
});
キュー トリガー、SqlQuery を使用した複数のドキュメントの取得
次の例は、SQL クエリで指定されている複数のドキュメントを、キュー トリガーを使用してクエリ パラメーターをカスタマイズすることで取得する TypeScript 関数を示しています。
キュー トリガーがパラメーター departmentId を提供します。 { "departmentId" : "Finance" } のキュー メッセージは、金融部門のすべてのレコードを返します。
import { app, input, InvocationContext } from '@azure/functions';
const cosmosInput = input.cosmosDB({
databaseName: 'MyDb',
collectionName: 'MyCollection',
sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
connectionStringSetting: 'CosmosDBConnection',
});
interface MyDocument {}
export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
for (const document of documents) {
// operate on each document
}
}
app.storageQueue('storageQueueTrigger1', {
queueName: 'outqueue',
connection: 'MyStorageConnectionAppSetting',
extraInputs: [cosmosInput],
handler: storageQueueTrigger1,
});
このセクションには、次の例が含まれています。各例では、さまざまなソースから ID 値を指定して単一のドキュメントを読み取ります。
- キュー トリガー、JSON からの ID の検索
- HTTP トリガー、クエリ文字列からの ID の検索
- HTTP トリガー、ルート データからの ID の検索
- キュー トリガー、SqlQuery を使用した複数のドキュメントの取得
キュー トリガー、JSON からの ID の検索
次の例は、単一のドキュメントを読み取り、そのドキュメントのテキスト値を更新する JavaScript 関数を示しています。
const { app, input, output } = require('@azure/functions');
const cosmosInput = input.cosmosDB({
databaseName: 'MyDatabase',
collectionName: 'MyCollection',
id: '{queueTrigger}',
partitionKey: '{queueTrigger}',
connectionStringSetting: 'MyAccount_COSMOSDB',
});
const cosmosOutput = output.cosmosDB({
databaseName: 'MyDatabase',
collectionName: 'MyCollection',
createIfNotExists: false,
partitionKey: '{queueTrigger}',
connectionStringSetting: 'MyAccount_COSMOSDB',
});
app.storageQueue('storageQueueTrigger1', {
queueName: 'outqueue',
connection: 'MyStorageConnectionAppSetting',
extraInputs: [cosmosInput],
extraOutputs: [cosmosOutput],
handler: (queueItem, context) => {
const doc = context.extraInputs.get(cosmosInput);
doc.text = 'This was updated!';
context.extraOutputs.set(cosmosOutput, doc);
},
});
HTTP トリガー、クエリ文字列からの ID の検索
次の例は、単一のドキュメントを取得する JavaScript 関数を示しています。 関数は、クエリ文字列を使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
const { app, input } = require('@azure/functions');
const cosmosInput = input.cosmosDB({
databaseName: 'ToDoItems',
collectionName: 'Items',
id: '{Query.id}',
partitionKey: '{Query.partitionKeyValue}',
connectionStringSetting: 'CosmosDBConnection',
});
app.http('httpTrigger1', {
methods: ['GET', 'POST'],
authLevel: 'anonymous',
extraInputs: [cosmosInput],
handler: (request, context) => {
const toDoItem = context.extraInputs.get(cosmosInput);
if (!toDoItem) {
return {
status: 404,
body: 'ToDo item not found',
};
} else {
return {
body: `Found ToDo item, Description=${toDoItem.Description}`,
};
}
},
});
HTTP トリガー、ルート データからの ID の検索
次の例は、単一のドキュメントを取得する JavaScript 関数を示しています。 関数は、ルート データを使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
const { app, input } = require('@azure/functions');
const cosmosInput = input.cosmosDB({
databaseName: 'ToDoItems',
collectionName: 'Items',
id: '{id}',
partitionKey: '{partitionKeyValue}',
connectionStringSetting: 'CosmosDBConnection',
});
app.http('httpTrigger1', {
methods: ['GET', 'POST'],
authLevel: 'anonymous',
route: 'todoitems/{partitionKeyValue}/{id}',
extraInputs: [cosmosInput],
handler: (request, context) => {
const toDoItem = context.extraInputs.get(cosmosInput);
if (!toDoItem) {
return {
status: 404,
body: 'ToDo item not found',
};
} else {
return {
body: `Found ToDo item, Description=${toDoItem.Description}`,
};
}
},
});
キュー トリガー、SqlQuery を使用した複数のドキュメントの取得
次の例は、SQL クエリで指定されている複数のドキュメントを、キュー トリガーを使用してクエリ パラメーターをカスタマイズすることで取得する JavaScript 関数を示しています。
キュー トリガーがパラメーター departmentId を提供します。 { "departmentId" : "Finance" } のキュー メッセージは、金融部門のすべてのレコードを返します。
const { app, input } = require('@azure/functions');
const cosmosInput = input.cosmosDB({
databaseName: 'MyDb',
collectionName: 'MyCollection',
sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
connectionStringSetting: 'CosmosDBConnection',
});
app.storageQueue('storageQueueTrigger1', {
queueName: 'outqueue',
connection: 'MyStorageConnectionAppSetting',
extraInputs: [cosmosInput],
handler: (queueItem, context) => {
const documents = context.extraInputs.get(cosmosInput);
for (const document of documents) {
// operate on each document
}
},
});
- キュー トリガー、JSON からの ID の検索
- HTTP トリガー、クエリ文字列からの ID の検索
- HTTP トリガー、ルート データからの ID の検索
- キュー トリガー、SqlQuery を使用した複数のドキュメントの取得
キュー トリガー、JSON からの ID の検索
次の例は、1 つの Azure Cosmos DB ドキュメントを読み取り、更新する方法を示しています。 ドキュメントの一意識別子は、キュー メッセージの JSON 値によって提供されます。
Azure Cosmos DB 入力バインドは、関数の構成ファイル (function.json) で見つかったバインドの一覧の先頭に表示されます。
{
"name": "InputDocumentIn",
"type": "cosmosDB",
"databaseName": "MyDatabase",
"collectionName": "MyCollection",
"id": "{queueTrigger_payload_property}",
"partitionKey": "{queueTrigger_payload_property}",
"connectionStringSetting": "CosmosDBConnection",
"direction": "in"
},
{
"name": "InputDocumentOut",
"type": "cosmosDB",
"databaseName": "MyDatabase",
"collectionName": "MyCollection",
"createIfNotExists": false,
"partitionKey": "{queueTrigger_payload_property}",
"connectionStringSetting": "CosmosDBConnection",
"direction": "out"
}
run.ps1 ファイルには、受信ドキュメントを読み取り、変更を出力する PowerShell コードが含まれます。
param($QueueItem, $InputDocumentIn, $TriggerMetadata)
$Document = $InputDocumentIn
$Document.text = 'This was updated!'
Push-OutputBinding -Name InputDocumentOut -Value $Document
HTTP トリガー、クエリ文字列からの ID の検索
次の例は、Web API から 1 つの Azure Cosmos DB ドキュメントを読み取り、更新する方法を示しています。 ドキュメントの一意識別子は、バインドの "Id": "{Query.Id}" プロパティで定義されているように、HTTP 要求の querystring パラメーターを通じて提供されます。
Azure Cosmos DB 入力バインドは、関数の構成ファイル (function.json) で見つかったバインドの一覧の先頭に表示されます。
{
"bindings": [
{
"type": "cosmosDB",
"name": "ToDoItem",
"databaseName": "ToDoItems",
"collectionName": "Items",
"connectionStringSetting": "CosmosDBConnection",
"direction": "in",
"Id": "{Query.id}",
"PartitionKey": "{Query.partitionKeyValue}"
},
{
"authLevel": "anonymous",
"name": "Request",
"type": "httpTrigger",
"direction": "in",
"methods": [
"get",
"post"
]
},
{
"name": "Response",
"type": "http",
"direction": "out"
},
],
"disabled": false
}
run.ps1 ファイルには、受信ドキュメントを読み取り、変更を出力する PowerShell コードが含まれます。
using namespace System.Net
param($Request, $ToDoItem, $TriggerMetadata)
Write-Host 'PowerShell HTTP trigger function processed a request'
if (-not $ToDoItem) {
Write-Host 'ToDo item not found'
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
StatusCode = [HttpStatusCode]::NotFound
Body = $ToDoItem.Description
})
} else {
Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
StatusCode = [HttpStatusCode]::OK
Body = $ToDoItem.Description
})
}
HTTP トリガー、ルート データからの ID の検索
次の例は、Web API から 1 つの Azure Cosmos DB ドキュメントを読み取り、更新する方法を示しています。 ドキュメントの一意識別子は、route パラメーターを通じて提供されます。 route パラメーターは、HTTP 要求バインドの route プロパティで定義され、Azure Cosmos DB "Id": "{Id}" バインド プロパティで参照されます。
Azure Cosmos DB 入力バインドは、関数の構成ファイル (function.json) で見つかったバインドの一覧の先頭に表示されます。
{
"bindings": [
{
"type": "cosmosDB",
"name": "ToDoItem",
"databaseName": "ToDoItems",
"collectionName": "Items",
"connectionStringSetting": "CosmosDBConnection",
"direction": "in",
"Id": "{id}",
"PartitionKey": "{partitionKeyValue}"
},
{
"authLevel": "anonymous",
"name": "Request",
"type": "httpTrigger",
"direction": "in",
"methods": [
"get",
"post"
],
"route": "todoitems/{partitionKeyValue}/{id}"
},
{
"name": "Response",
"type": "http",
"direction": "out"
}
],
"disabled": false
}
run.ps1 ファイルには、受信ドキュメントを読み取り、変更を出力する PowerShell コードが含まれます。
using namespace System.Net
param($Request, $ToDoItem, $TriggerMetadata)
Write-Host 'PowerShell HTTP trigger function processed a request'
if (-not $ToDoItem) {
Write-Host 'ToDo item not found'
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
StatusCode = [HttpStatusCode]::NotFound
Body = $ToDoItem.Description
})
} else {
Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
StatusCode = [HttpStatusCode]::OK
Body = $ToDoItem.Description
})
}
キュー トリガー、SqlQuery を使用した複数のドキュメントの取得
次の例は、複数の Azure Cosmos DB ドキュメントを読み取る方法を示しています。 関数の構成ファイル (function.json) によって、sqlQuery を含むバインド プロパティが定義されます。 sqlQuery プロパティに指定された SQL ステートメントによって、関数に提供されるドキュメントのセットが選択されます。
{
"name": "Documents",
"type": "cosmosDB",
"direction": "in",
"databaseName": "MyDb",
"collectionName": "MyCollection",
"sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
"connectionStringSetting": "CosmosDBConnection"
}
run1.ps1 ファイルには、受信ドキュメントを読み取る PowerShell コードが含まれます。
param($QueueItem, $Documents, $TriggerMetadata)
foreach ($Document in $Documents) {
# operate on each document
}
このセクションには、次の例が含まれています。各例では、さまざまなソースから ID 値を指定して単一のドキュメントを読み取ります。
- キュー トリガー、JSON からの ID の検索
- HTTP トリガー、クエリ文字列からの ID の検索
- HTTP トリガー、ルート データからの ID の検索
- キュー トリガー、SqlQuery を使用した複数のドキュメントの取得
この例は、v1 と v2 のどちらの Python プログラミング モデルを使用するかによって異なります。
キュー トリガー、JSON からの ID の検索
次の例は、Azure Cosmos DB 入力バインドを示しています。 この関数は、1 つのドキュメントを読み取って、そのドキュメントのテキスト値を更新します。
import logging
import azure.functions as func
app = func.FunctionApp()
@app.queue_trigger(arg_name="msg",
queue_name="outqueue",
connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents",
database_name="MyDatabase",
collection_name="MyCollection",
id="{msg.payload_property}",
partition_key="{msg.payload_property}",
connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument",
database_name="MyDatabase",
collection_name="MyCollection",
connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
inputDocument: func.DocumentList,
outputDocument: func.Out[func.Document]):
document = documents[id]
document["text"] = "This was updated!"
doc = inputDocument[0]
doc["text"] = "This was updated!"
outputDocument.set(doc)
print(f"Updated document.")
HTTP トリガー、クエリ文字列からの ID の検索
次の例は、単一のドキュメントを取得する関数を示しています。 関数は、クエリ文字列を使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
HTTP トリガー、ルート データからの ID の検索
次の例は、単一のドキュメントを取得する関数を示しています。 関数は、ルート データを使用して検索のための ID とパーティション キー値を指定する HTTP 要求によってトリガーされます。 その ID とパーティション キー値は、指定されたデータベースとコレクションから ToDoItem ドキュメントを取得するために使用されます。
キュー トリガー、SqlQuery を使用した複数のドキュメントの取得
次の例は、バインドが使用される Azure Cosmos DB 入力バインド Python 関数を示しています。 この関数は、SQL クエリで指定されている複数のドキュメントを、キュー トリガーを使用してクエリ パラメーターをカスタマイズすることで取得します。
キュー トリガーがパラメーター departmentId を提供します。 { "departmentId" : "Finance" } のキュー メッセージは、金融部門のすべてのレコードを返します。
属性
インプロセスと分離ワーカー プロセスの C# ライブラリの両方で、属性を使って関数を定義します。 C# スクリプトでは、C# スクリプト ガイドで説明されているように、代わりに function.json 構成ファイルを使用します。
| 属性のプロパティ | 説明 |
|---|---|
| 接続 | クエリ対象の Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定のコレクションの名前。 詳細については、「接続」を参照してください。 |
| DatabaseName | 監視対象のコンテナーを含む Azure Cosmos DB データベースの名前。 |
| ContainerName | 監視対象のコンテナーの名前。 |
| PartitionKey | 参照用のパーティション キー値を指定します。 バインディング パラメーターを含めることもできます。 パーティション分割されたコンテナーの検索に必要です。 |
| Id | 取得するドキュメントの ID。 このプロパティは、バインド式をサポートしています。 Id と SqlQuery プロパティの両方は設定しないでください。 いずれも設定しなかった場合は、コンテナー全体が取得されます。 |
| SqlQuery | 複数のドキュメントを取得するときに使用する Azure Cosmos DB SQL クエリ。 このプロパティは、次の例のように実行時のバインドをサポートします。SELECT * FROM c where c.departmentId = {departmentId} Id と SqlQuery プロパティの両方は設定しないでください。 いずれも設定しなかった場合は、コンテナー全体が取得されます。 |
| PreferredLocations | (省略可能) Azure Cosmos DB サービスの geo レプリケートされたデータベース アカウントの優先される場所 (リージョン) を定義します。 複数の値はコンマで区切る必要があります。 たとえば、East US,South Central US,North Europe のようにします。 |
デコレータ
"Python v2 プログラミング モデルにのみ適用されます。"
デコレータを使用して定義された Python v2 関数の場合、cosmos_db_input に次のプロパティがあります。
| プロパティ | 説明 |
|---|---|
arg_name |
変更されるドキュメントの一覧を表す、関数コードで使用する変数の名前。 |
database_name |
監視されているコレクションを使用する Azure Cosmos DB データベースの名前。 |
collection_name |
監視対象の Azure Cosmos DB コレクションの名前。 |
connection_string_setting |
監視対象の Azure Cosmos DB の接続文字列。 |
partition_key |
監視対象の Azure Cosmos DB のパーティション キー。 |
id |
取得するドキュメントの ID。 |
function.json を使用して定義された Python 関数については、「構成」セクションを参照してください。
注釈
Java 関数ランタイム ライブラリから、Azure Cosmos DB からデータを読み取るパラメーターに対して @CosmosDBInput 注釈を使用します。 この注釈では、次のプロパティがサポートされます。
構成
"Python v1 プログラミング モデルにのみ適用されます。"
次の表では、function.json ファイルで設定するバインド構成のプロパティについて説明します。これらのプロパティは、拡張機能バージョンによって異なります。
| function.json のプロパティ | 説明 |
|---|---|
| type | cosmosDB に設定する必要があります。 |
| direction | in に設定する必要があります。 |
| name | 変更されるドキュメントの一覧を表す、関数コードで使用する変数の名前。 |
| connection | 監視対象の Azure Cosmos DB アカウントへの接続方法を指定するアプリの設定または設定コンテナーの名前。 詳細については、「接続」を参照してください。 |
| databaseName | 監視対象のコンテナーを含む Azure Cosmos DB データベースの名前。 |
| containerName | 監視対象のコンテナーの名前。 |
| partitionKey | 参照用のパーティション キー値を指定します。 バインディング パラメーターを含めることもできます。 パーティション分割されたコンテナーの検索に必要です。 |
| id | 取得するドキュメントの ID。 このプロパティは、バインド式をサポートしています。 id と sqlQuery プロパティの両方は設定しないでください。 いずれも設定しなかった場合は、コンテナー全体が取得されます。 |
| sqlQuery | 複数のドキュメントを取得するときに使用する Azure Cosmos DB SQL クエリ。 このプロパティは、次の例のように実行時のバインドをサポートします。SELECT * FROM c where c.departmentId = {departmentId} id と sqlQuery プロパティの両方は設定しないでください。 いずれも設定しなかった場合は、コンテナー全体が取得されます。 |
| preferredLocations | (省略可能) Azure Cosmos DB サービスの geo レプリケートされたデータベース アカウントの優先される場所 (リージョン) を定義します。 複数の値はコンマで区切る必要があります。 たとえば、「 East US,South Central US,North Europe 」のように入力します。 |
完全な例については、セクションの例を参照してください。
使用法
関数が正常に終了すると、入力ドキュメントへの変更がすべて自動的に保持されます。
Cosmos DB 入力バインドでサポートされるパラメーターの型は、Functions ランタイムのバージョン、拡張機能パッケージのバージョン、使用される C# のモダリティによって異なります。
サポートされる型の一覧については、「バインドの種類」を参照してください。
Java 関数ランタイム ライブラリの @CosmosDBInput 注釈によって Azure Cosmos DB データは関数に公開されます。 この注釈は、Java のネイティブ型、POJO、または Optional<T> を使用した null 許容値で使用できます。
関数の終了時にドキュメントへの更新が自動的に行われることはありません。 関数でドキュメントを更新するには、出力バインドを使用します。 詳細については、「PowerShell の例」を参照してください。
データは、DocumentList パラメーターを介して関数から使用できるようになります。 ドキュメントに加えられた変更は、自動的には保存されません。
接続
connectionStringSetting/connection プロパティと leaseConnectionStringSetting/leaseConnection プロパティは、アプリを Azure Cosmos DB に接続する方法を指定する環境構成への参照です。 以下を指定できます。
- 接続文字列を含むアプリケーション設定の名前。
- まとめて ID ベースの接続を定義する、複数のアプリケーション設定の共有プレフィックスの名前。 このオプションは、
connectionのconnectionおよびleaseConnectionバージョンでのみ使用できます。
構成された値が、1 つの設定に完全一致し、プレフィックスがその他の設定とも一致する場合は、完全一致が使用されます。
接続文字列
お使いのデータベース アカウントの接続文字列を、バインディング構成の接続プロパティで指定した値と同じ名前のアプリケーション設定に格納する必要があります。
ID ベースの接続
バージョン 4.x 以上の拡張機能を使用する場合は、シークレットを含む接続文字列を使う代わりに、アプリで Azure Active Directory ID を使用できます。 これを行うには、トリガーおよびバインディング構成の接続プロパティにマップされる共通のプレフィックスに設定を定義します。
このモードでは、拡張機能に次のプロパティが必要です。
| プロパティ | 環境変数テンプレート | 説明 | 値の例 |
|---|---|---|---|
| アカウント エンドポイント | <CONNECTION_NAME_PREFIX>__accountEndpoint |
Azure Cosmos DB アカウント エンドポイント URI。 | https://<database_account_name>.documents.azure.com:443/ |
接続をカスタマイズするには、プロパティを追加設定します。 「ID ベース接続に共通のプロパティ」を参照してください。
Azure Functions サービスでホストされている場合、ID ベースの接続では、マネージド ID が使用されます。 ユーザー割り当て ID を credential および clientID プロパティで指定できますが、システム割り当て ID が既定で使用されます。 リソース ID を使用したユーザー割り当て ID の構成はサポートされていないことに注意してください。 ローカル開発などの他のコンテキストで実行する場合は、代わりに開発者 ID が使用されますが、カスタマイズすることもできます。 ID ベースの接続によるローカル開発に関するページをご覧ください。
ID にアクセス許可を付与する
使用されている ID が何であれ、目的のアクションを実行するためのアクセス許可が必要です。 ほとんどの Azure では、これはそれらのアクセス許可を提供する組み込みロールまたはカスタム ロールを使って、Azure RBAC でロールを割り当てる必要があることを意味します。
重要
すべてのコンテキストに必要ではない一部のアクセス許可がターゲット サービスによって公開される場合があります。 可能であれば、最小限の特権の原則に従い、必要な特権だけを ID に付与します。 たとえば、アプリがデータ ソースからの読み取りのみを行う必要がある場合は、読み取りアクセス許可のみを持つロールを使用します。 サービスへの書き込みも可能なロールを割り当てることは、読み取り操作に対するアクセス許可が過剰になるため、不適切です。 同様に、ロールの割り当てが、読み取る必要のあるリソースだけに限定されていることを確認する必要があります。
Cosmos DB では、データ操作に Azure RBAC は使われません。 代わりに、同様の概念に基づいて構築された Cosmos DB の組み込み RBAC システムが使われます。 実行時にデータベース アカウントへのアクセスを提供するロールの割り当てを作成する必要があります。 所有者のような Azure RBAC 管理ロールでは十分ではありません。 次の表は、通常の操作で Azure Cosmos DB の拡張機能を使用するときに推奨される組み込みのロールを示しています。 アプリケーションでは、記述したコードに基づいて追加のアクセス許可が必要になる場合があります。
| [バインドの種類] | 組み込みロールの例 1 |
|---|---|
| トリガー 2 | Cosmos DB 組み込みデータ共同作成者 |
| 入力バインド | Cosmos DB 組み込みデータ リーダー |
| 出力バインド | Cosmos DB 組み込みデータ共同作成者 |
1 これらのロールは、Azure RBAC ロールの割り当てでは使用できません。 これらのロールの割り当て方法について詳しくは、Cosmos DB の組み込み RBAC システムに関するドキュメントをご覧ください。
2 ID を使うと、Cosmos DB はコンテナーの作成を管理操作として扱います。 トリガーのデータ プレーン操作としては使用できません。 関数を設定する前に、トリガーで必要なコンテナー (リース コンテナーを含む) を作成する必要があります。