Azure Functions における Azure Blob Storage の出力バインド

出力バインドを使用すると、Azure 関数内で Blob Storage データを変更および削除できます。

セットアップと構成の詳細については、概要を参照してください。

次の例は、1 つの BLOB トリガーと 2 つの出力 BLOB バインディングを使用するC# 関数です。 関数は、sample-images コンテナーのイメージ BLOB の作成によってトリガーされます。 イメージ BLOB の小規模および中規模サイズのコピーを作成します。

using System.Collections.Generic;
using System.IO;
using Microsoft.Azure.WebJobs;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Formats;
using SixLabors.ImageSharp.PixelFormats;
using SixLabors.ImageSharp.Processing;

public class ResizeImages
{
    [FunctionName("ResizeImage")]
    public static void Run([BlobTrigger("sample-images/{name}")] Stream image,
        [Blob("sample-images-sm/{name}", FileAccess.Write)] Stream imageSmall,
        [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageMedium)
    {
        IImageFormat format;

        using (Image<Rgba32> input = Image.Load<Rgba32>(image, out format))
        {
            ResizeImage(input, imageSmall, ImageSize.Small, format);
        }

        image.Position = 0;
        using (Image<Rgba32> input = Image.Load<Rgba32>(image, out format))
        {
            ResizeImage(input, imageMedium, ImageSize.Medium, format);
        }
    }

    public static void ResizeImage(Image<Rgba32> input, Stream output, ImageSize size, IImageFormat format)
    {
        var dimensions = imageDimensionsTable[size];

        input.Mutate(x => x.Resize(dimensions.Item1, dimensions.Item2));
        input.Save(output, format);
    }

    public enum ImageSize { ExtraSmall, Small, Medium }

    private static Dictionary<ImageSize, (int, int)> imageDimensionsTable = new Dictionary<ImageSize, (int, int)>() {
        { ImageSize.ExtraSmall, (320, 200) },
        { ImageSize.Small,      (640, 400) },
        { ImageSize.Medium,     (800, 600) }
    };

}

属性と注釈

C# クラス ライブラリでは、BlobAttributeを使用します。

次の例で示すように、属性のコンストラクターは、BLOB へのパスと、読み取りまたは書き込みを示す FileAccess パラメーターを受け取ります。

[FunctionName("ResizeImage")]
public static void Run(
    [BlobTrigger("sample-images/{name}")] Stream image,
    [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
{
    ...
}

次の例で示すように、Connection プロパティを設定して、使用するストレージ アカウントを指定できます。

[FunctionName("ResizeImage")]
public static void Run(
    [BlobTrigger("sample-images/{name}")] Stream image,
    [Blob("sample-images-md/{name}", FileAccess.Write, Connection = "StorageConnectionAppSetting")] Stream imageSmall)
{
    ...
}

完全な例については、「出力 - 例」を参照してください。

StorageAccount 属性を使用して、クラス、メソッド、またはパラメーターのレベルでストレージ アカウントを指定できます。 詳細については、トリガー - 属性をご覧ください。

構成

次の表は、function.json ファイルと 属性で設定したバインド構成のプロパティを説明しています。

function.json のプロパティ 属性のプロパティ 説明
type 該当なし blob に設定する必要があります。
direction 該当なし 出力バインディングの場合は out に設定する必要があります。 例外は、使用方法のセクションに記載しています。
name 該当なし 関数コード内の BLOB を表す変数の名前。 $return に設定して、関数の戻り値を参照します。
path BlobPath BLOB コンテナーへのパス。
connection 接続 Azure Blob への接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。
該当なし Access (アクセス) 読み取りと書き込みのどちらを行うかを示します。

ローカルで開発している場合、アプリ設定は local.settings.json ファイルに保存されます。

接続

connection プロパティは、アプリを Azure BLOB に接続する方法を指定する環境構成への参照です。 次が指定される場合があります。

  • 接続文字列を含むアプリケーション設定の名前
  • まとめて ID ベースの接続を定義する、複数のアプリケーション設定の共有プレフィックスの名前。

構成された値が、1 つの設定に完全一致し、プレフィックスがその他の設定とも一致する場合は、完全一致が使用されます。

接続文字列

接続文字列を取得するには、「ストレージ アカウント アクセス キーを管理する」の手順に従います。 接続文字列は、BLOB ストレージ アカウントではなく汎用ストレージ アカウントに対するものである必要があります。

この接続文字列は、バインディング構成の connection プロパティで指定した値と同じ名前のアプリケーション設定に格納する必要があります。

アプリ設定の名前が "AzureWebJobs" で始まる場合は、ここで名前の残りの部分のみを指定できます。 たとえば、connection を "MyStorage" に設定した場合、Functions ランタイムは "AzureWebJobsMyStorage" という名前のアプリ設定を探します。connection を空のままにした場合、Functions ランタイムは、アプリ設定内の AzureWebJobsStorage という名前の既定のストレージ接続文字列を使用します。

ID ベースの接続

バージョン 5.x 以上の拡張機能を使用する場合は、シークレットを含む接続文字列の代わりに、アプリで Azure Active Directory ID を使用することができます。 これを行うには、トリガーおよびバインド構成の connection プロパティにマップされる共通のプレフィックスに設定を定義します。

このモードでは、拡張機能に次のプロパティが必要です。

プロパティ 環境変数テンプレート 説明 値の例
Blob Service の URI <CONNECTION_NAME_PREFIX>__serviceUri<CONNECTION_NAME_PREFIX>__serviceUri HTTPS スキームを使用して接続している BLOB サービスのデータ プレーン URI。 https://<storage_account_name>.blob.core.windows.net

1 をエイリアスとして使用できます。 接続構成が BLOB トリガーによって使用される場合、blobServiceUri には queueServiceUri も指定する必要があります。 以下を参照してください。

接続をカスタマイズするには、プロパティを追加設定します。 「ID ベース接続に共通のプロパティ」を参照してください。

serviceUri 形式は、全体の接続構成が BLOB、キュー、テーブル間で使用される場合は、使用できません。 URI 自体は BLOB サービスのみを指定できます。 別の方法として、サービスごとに専用の URI を指定して、1 つの接続を使用できるようにすることができます。 両方のバージョンが指定された場合、マルチサービス形式が使用されます。 複数のサービス用の接続を構成するには、<CONNECTION_NAME_PREFIX>__serviceUri の代わりに次を設定します。

プロパティ 環境変数テンプレート 説明 値の例
Blob Service の URI <CONNECTION_NAME_PREFIX>__blobServiceUri HTTPS スキームを使用して接続している BLOB サービスのデータ プレーン URI。 https://<storage_account_name>.blob.core.windows.net
Queue Service URI (BLOB トリガーに必要2) <CONNECTION_NAME_PREFIX>__queueServiceUri HTTPS スキームを使用したキュー サービスのデータ プレーン URI。 この値は、BLOB トリガーにのみ必要です。 https://<storage_account_name>.queue.core.windows.net

2 既定で、BLOB トリガーでは Azure キューが内部で使用されます。 serviceUri 形式では、AzureWebJobsStorage 接続が使用されます。 ただし、blobServiceUri を指定する場合は、queueServiceUri でキュー サービス URI も指定する必要があります。 BLOB サービスと同じストレージ アカウントからサービスを使用することをお勧めします。 また、トリガーでは、ストレージ キュー データ共同作成者のようなロールを割り当てることによって、構成されたキュー サービスのメッセージを読み書きできるようにする必要があります。

Azure Functions サービスでホストされている場合、ID ベースの接続では、マネージド ID が使用されます。 ユーザー割り当て ID を credential および clientID プロパティで指定できますが、システム割り当て ID が既定で使用されます。 ローカル開発などの他のコンテキストで実行する場合は、代わりに開発者 ID が使用されますが、カスタマイズすることもできます。 ID ベースの接続によるローカル開発に関するページをご覧ください。

ID にアクセス許可を付与する

使用されている ID が何であれ、目的のアクションを実行するためのアクセス許可が必要です。 これらのアクセス許可を提供する組み込みロールまたはカスタム ロールを使用して、Azure RBAC でロールを割り当てる必要があります。

重要

すべてのコンテキストに必要ではない一部のアクセス許可がターゲット サービスによって公開される場合があります。 可能であれば、最小限の特権の原則に従い、必要な特権だけを ID に付与します。 たとえば、アプリがデータ ソースからの読み取りのみを行う必要がある場合は、読み取りアクセス許可のみを持つロールを使用します。 サービスへの書き込みも可能なロールを割り当てることは、読み取り操作に対するアクセス許可が過剰になるため、不適切です。 同様に、ロールの割り当てが、読み取る必要のあるリソースだけに限定されていることを確認する必要があります。

実行時に BLOB コンテナーへのアクセスを提供するロールの割り当てを作成する必要があります。 所有者のような管理ロールでは十分ではありません。 次の表は、通常の操作で Blob Storage の拡張機能を使用するときに推奨される組み込みロールを示しています。 アプリケーションでは、記述したコードに基づいて追加のアクセス許可が必要になる場合があります。

[バインドの種類] 組み込みロールの例
トリガー ストレージ BLOB データ所有者およびストレージ キュー データ共同作成者1
入力バインド ストレージ BLOB データ閲覧者
出力バインド ストレージ BLOB データ所有者

1 既定で、BLOB トリガーでは Azure キューが内部で使用されます。 そのため、メッセージの作成と受信のためのストレージ キュー データ共同作成者のアクセス許可も必要です。

使用法

Default

次の型にバインドして BLOB を書き込むことができます。

  • TextWriter
  • out string
  • out Byte[]
  • CloudBlobStream
  • Stream
  • CloudBlobContainerCloudBlobContainer
  • CloudBlobDirectory
  • ICloudBlobICloudBlob
  • CloudBlockBlobCloudBlockBlob
  • CloudPageBlobCloudPageBlob
  • CloudAppendBlobCloudAppendBlob

1function.json には "in" バインド 、C# クラス ライブラリには が必要です。 ただし、コンテナーへの BLOB のアップロードなどの書き込み操作をおこなうためにランタイムが提供するコンテナー オブジェクトを使うことができます。

2function.json には "inout" バインド 、C# クラス ライブラリには が必要です。

Storage SDK タイプの 1 つにバインドしようとしてエラー メッセージが表示された場合は、適切な Storage SDK バージョンへの参照があることをご確認ください。

string または Byte[] へのバインドが推奨されるのは、BLOB のサイズが小さい場合のみです (BLOB 全体のコンテンツがメモリに読み込まれるため)。 通常、Stream 型または CloudBlockBlob 型の使用が推奨されます。 詳しくは、この記事で前述した「コンカレンシーとメモリ使用量」セクションをご覧ください。

その他の型

Storage 拡張機能の 5.0.0 またはそれ以降のバージョンを使用するアプリでは、Azure SDK for .NET の型を使用することもできます。 このバージョンでは、次の型を優先して、レガシ CloudBlobContainerCloudBlobDirectoryICloudBlobCloudBlockBlobCloudPageBlobCloudAppendBlob 型のサポートがなくなります。

1function.json には "in" バインド 、C# クラス ライブラリには が必要です。 ただし、コンテナーへの BLOB のアップロードなどの書き込み操作をおこなうためにランタイムが提供するコンテナー オブジェクトを使うことができます。

2function.json には "inout" バインド 、C# クラス ライブラリには が必要です。

これらの型の使用例については、拡張機能の GitHub リポジトリに関するページを参照してください。 これらの異なる新しい型と、それらを移行する方法については、Azure.Storage.Blobs の移行ガイドに関するページを参照してください。

例外とリターン コード

バインド リファレンス
BLOB BLOB エラー コード
BLOB、テーブル、キュー ストレージ エラー コード
BLOB、テーブル、キュー トラブルシューティング

次のステップ