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

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

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

A C# 関数は、次の C# モードのいずれかを使用して作成できます。

  •     インプロセス クラス ライブラリ: Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数。
  • 分離ワーカー プロセス クラス ライブラリ: ランタイムから分離されたワーカー プロセスで実行されるコンパイル済みの C# 関数。 分離ワーカー プロセスは、非 LTS バージョンの .NET および.NET Framework で実行されている C# 関数をサポートするために必要です。
  • C# スクリプト: Azure portal で c# 関数を作成するときに主に使用されます。

次の例は、インプロセスで動作し、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) }
    };

}

このセクションには、次の例が含まれています。

HTTP トリガー、OutputBinding を使用する (Java)

次の例では、Java 関数が HttpTrigger 注釈を利用し、BLOB ストレージ コンテナーのファイル名を含むパラメーターを受け取ります。 BlobInput 注釈によってファイルが読み取られ、その内容が byte[] として関数に渡されます。 BlobOutput 注釈が OutputBinding outputItem にバインドされます。OutputBinding が関数によって使用され、構成済みのストレージ コンテナーに入力 BLOB の内容が書き込まれます。

  @FunctionName("copyBlobHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage copyBlobHttp(
    @HttpTrigger(name = "req", 
      methods = {HttpMethod.GET}, 
      authLevel = AuthorizationLevel.ANONYMOUS) 
    HttpRequestMessage<Optional<String>> request,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{Query.file}") 
    byte[] content,
    @BlobOutput(
      name = "target", 
      path = "myblob/{Query.file}-CopyViaHttp")
    OutputBinding<String> outputItem,
    final ExecutionContext context) {
      // Save blob to outputItem
      outputItem.setValue(new String(content, StandardCharsets.UTF_8));

      // build HTTP response with size of requested blob
      return request.createResponseBuilder(HttpStatus.OK)
        .body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
        .build();
  }

キュー トリガー、関数戻り値を使用する (Java)

次の例では、Java 関数が QueueTrigger 注釈を利用し、BLOB ストレージ コンテナーのファイル名を含むメッセージを受け取ります。 BlobInput 注釈によってファイルが読み取られ、その内容が byte[] として関数に渡されます。 BlobOutput 注釈が関数戻り値にバインドされます。この関数戻り値がランタイムによって使用され、構成済みのストレージ コンテナーに入力 BLOB の内容が書き込まれます。

  @FunctionName("copyBlobQueueTrigger")
  @StorageAccount("Storage_Account_Connection_String")
  @BlobOutput(
    name = "target", 
    path = "myblob/{queueTrigger}-Copy")
  public String copyBlobQueue(
    @QueueTrigger(
      name = "filename", 
      dataType = "string",
      queueName = "myqueue-items") 
    String filename,
    @BlobInput(
      name = "file", 
      path = "samples-workitems/{queueTrigger}") 
    String content,
    final ExecutionContext context) {
      context.getLogger().info("The content of \"" + filename + "\" is: " + content);
      return content;
  }

Java 関数ランタイム ライブラリ で、その値が Blob Storage のオブジェクトに書き込まれる関数のパラメーター上で 注釈を使用します。 パラメーターの型は OutputBinding<T> にする必要があります。T は Java の任意のネイティブ型または POJO です。

次の例は、function.json ファイルの BLOB 入出力バインドと、そのバインドを使用する JavaScript コードを示しています。 関数は、BLOB のコピーを作成します。 関数は、コピーする BLOB の名前を含むキュー メッセージによってトリガーされます。 新しい BLOB の名前は {originalblobname}-Copy です。

function.json ファイルでは、 メタデータ プロパティは path プロパティ内の BLOB 名の指定に使用されます。

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "myQueueItem",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

これらのプロパティについては、「構成」セクションを参照してください。

JavaScript コードを次に示します。

module.exports = async function(context) {
    context.log('Node.js Queue trigger function processed', context.bindings.myQueueItem);
    context.bindings.myOutputBlob = context.bindings.myInputBlob;
};

次の例は、PowerShell 関数からの出力として、受信 BLOB のコピーを作成する方法を示しています。

関数の構成ファイル (function.json) で、 メタデータ プロパティを使用して path プロパティ内の出力 BLOB 名を指定します。

Note

無限ループを回避するために、入力パスと出力パスが異なることを確認してください。

{
  "bindings": [
    {
      "name": "myInputBlob",
      "path": "data/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in",
      "type": "blobTrigger"
    },
    {
      "name": "myOutputBlob",
      "type": "blob",
      "path": "data/copy/{trigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false
}

PowerShell コードを次に示します。

# Input bindings are passed in via param block.
param([byte[]] $myInputBlob, $TriggerMetadata)
Write-Host "PowerShell Blob trigger function Processed blob Name: $($TriggerMetadata.Name)"
Push-OutputBinding -Name myOutputBlob -Value $myInputBlob

次の例は、function.json ファイルの BLOB 入出力バインドと、バインドを使用する Python スクリプト コードを示しています。 関数は、BLOB のコピーを作成します。 関数は、コピーする BLOB の名前を含むキュー メッセージによってトリガーされます。 新しい BLOB の名前は {originalblobname}-Copy です。

function.json ファイルでは、 メタデータ プロパティは path プロパティ内の BLOB 名の指定に使用されます。

{
  "bindings": [
    {
      "queueName": "myqueue-items",
      "connection": "MyStorageConnectionAppSetting",
      "name": "queuemsg",
      "type": "queueTrigger",
      "direction": "in"
    },
    {
      "name": "inputblob",
      "type": "blob",
      "dataType": "binary",
      "path": "samples-workitems/{queueTrigger}",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "in"
    },
    {
      "name": "outputblob",
      "type": "blob",
      "dataType": "binary",
      "path": "samples-workitems/{queueTrigger}-Copy",
      "connection": "MyStorageConnectionAppSetting",
      "direction": "out"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

これらのプロパティについては、「構成」セクションを参照してください。

Python コードを次に示します。

import logging
import azure.functions as func


def main(queuemsg: func.QueueMessage, inputblob: bytes, outputblob: func.Out[bytes]):
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    outputblob.set(inputblob)

属性

インプロセス分離ワーカー プロセスの C# ライブラリの両方で、属性を使用して関数を定義します。 代わりに、C# スクリプトでは、function.json 構成ファイルを使用します。

BlobAttribute 属性のコンストラクターは、次のパラメーターを受け取ります。

パラメーター 説明
BlobPath BLOB へのパス。
接続 Azure Blob への接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。
Access (アクセス) 読み取りと書き込みのどちらを行うかを示します。

次の例では、BLOB へのパスと、出力バインドの書き込みを示す FileAccess パラメーターを設定しています。

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

属性は Connection プロパティを受け取りますが、 Connection を使用してストレージ アカウント接続を指定することもできます。 これは、ライブラリ内の他の関数とは異なるストレージ アカウントを使用する必要がある場合に実行できます。 コンストラクターは、ストレージ接続文字列を含むアプリ設定の名前を受け取ります。 属性は、パラメーター、メソッド、またはクラス レベルで適用できます。 次の例では、クラス レベルとメソッド レベルを示します。

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

使用するストレージ アカウントは、次の順序で決定されます。

  • トリガーまたはバインド属性の Connection プロパティ。
  • トリガーまたはバインド属性と同じパラメーターに適用された StorageAccount 属性。
  • 関数に適用される StorageAccount 属性。
  • クラスに適用される StorageAccount 属性。
  • AzureWebJobsStorage アプリケーション設定で定義されている、関数アプリの既定のストレージ アカウント。

ローカルで開発する場合は、 コレクション内の local.settings.json ファイルにアプリケーション設定を追加します。

注釈

@BlobOutput 属性を使用すると、関数をトリガーした BLOB にアクセスできます。 この属性と共にバイト配列を使用する場合は、dataTypebinary に設定します。 詳細については、「出力 - 例」を参照してください。

構成

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

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

完全な例については、セクションの例を参照してください。

使用方法

BLOB 出力バインドの使用方法は、拡張機能パッケージのバージョンと、関数アプリで使用される C# のモダリティによって異なり、次のいずれかになります。

インプロセス クラス ライブラリは、Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数です。

バージョンを選択すると、モードとバージョンの使用状況の詳細が表示されます。

すべてのバージョンで、次のパラメーターの型がサポートされています。

  • Stream
  • TextReader
  • string
  • Byte[]

次のパラメーター型は拡張機能バージョン固有であり、 C# クラス ライブラリでは FileAccess.ReadWrite が必要です。

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

StorageAccountAttribute を使用して、使用するストレージ アカウントを指定することもできます。 これは、ライブラリ内の他の関数とは異なるストレージ アカウントを使用する必要がある場合に実行できます。 コンストラクターは、ストレージ接続文字列を含むアプリ設定の名前を受け取ります。 属性は、パラメーター、メソッド、またはクラス レベルで適用できます。 次の例では、クラス レベルとメソッド レベルを示します。

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("BlobTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ....
}

使用するストレージ アカウントは、次の順序で決定されます。

  • BlobTrigger 属性の Connection プロパティ。
  • BlobTrigger 属性と同じパラメーターに適用された StorageAccount 属性。
  • 関数に適用される StorageAccount 属性。
  • クラスに適用される StorageAccount 属性。
  • AzureWebJobsStorage アプリケーション設定で定義されている、関数アプリの既定のストレージ アカウント。

string または Byte[] へのバインドが推奨されるのは、BLOB のサイズが小さい場合のみです。 これが推奨されるのは、BLOB 全体の内容がメモリに読み込まれるためです。 ほとんどの BLOB では、Stream 型または CloudBlockBlob 型を使用します。 詳細については、「コンカレンシーとメモリ使用量」を参照してください。

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

@BlobOutput 属性を使用すると、関数をトリガーした BLOB にアクセスできます。 この属性と共にバイト配列を使用する場合は、dataTypebinary に設定します。 詳細については、「出力 - 例」を参照してください。

context.bindings.<BINDING_NAME> を使用して BLOB データにアクセスします。バインド名は context.bindings.<BINDING_NAME> ファイルで定義されています。

function.json ファイルのバインドの name パラメーターで指定されている名前と一致するパラメーターを使用して、BLOB データにアクセスします。

関数のパラメーターを次の型で宣言し、BLOB ストレージに書き込むことができます。

  • func.Out[str] は文字列
  • func.Out[func.InputStream] はストリーム

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

接続

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

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

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

接続文字列

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

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

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

ID ベースの接続

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

connection を "AzureWebJobsStorage" に設定する場合は、「connection」を参照してください。 その他のすべての接続では、拡張機能に次のプロパティが必要です。

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

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

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 トリガーは、複数回にわたる再試行の失敗を、有害な BLOB をキューに書き込むことで処理します。 serviceUri 形式では、AzureWebJobsStorage 接続が使用されます。 ただし、blobServiceUri を指定する場合は、queueServiceUri でキュー サービス URI も指定する必要があります。 BLOB サービスと同じストレージ アカウントからサービスを使用することをお勧めします。 また、トリガーでは、ストレージ キュー データ共同作成者のようなロールを割り当てることによって、構成されたキュー サービスのメッセージを読み書きできるようにする必要があります。

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

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

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

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

重要

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

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

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

AzureWebJobsStorage 接続にも追加のアクセス許可を付与する必要があります。2
入力バインド ストレージ BLOB データ閲覧者
出力バインド ストレージ BLOB データ所有者

1 BLOB トリガーは、複数回にわたる再試行の失敗を、接続によって指定されたストレージ アカウント上のキューに有害な BLOB を書き込むことにより処理します。

2 AzureWebJobsStorage 接続は、トリガーを有効にする BLOB やキューのために内部的に使用されます。 ID ベースの接続を使用するように構成されている場合は、既定の要件を超える追加のアクセス許可が必要になります。 これらは、ストレージ BLOB データ所有者ストレージ キュー データ共同作成者、およびストレージ アカウント共同作成者の各ロールによって満たされます。 詳細については、「ID を使用してホスト ストレージに接続する」を参照してください。

例外とリターン コード

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

次のステップ