Bagikan melalui

Pengikatan input penyimpanan Azure Blob untuk Azure Functions

  • Artikel

Pengikatan input memungkinkan Anda membaca data penyimpanan blob sebagai input ke Azure Functions.

Untuk informasi tentang pengaturan dan detail konfigurasi, lihat gambaran umum.

Penting

Artikel ini menggunakan tab untuk mendukung beberapa versi model pemrograman Node.js. Model v4 umumnya tersedia dan dirancang untuk memiliki pengalaman yang lebih fleksibel dan intuitif untuk pengembang JavaScript dan TypeScript. Untuk detail selengkapnya tentang cara kerja model v4, lihat panduan pengembang Node.js Azure Functions. Untuk mempelajari selengkapnya tentang perbedaan antara v3 dan v4, lihat panduan migrasi.

Azure Functions mendukung dua model pemrograman untuk Python. Cara Anda menentukan pengikatan tergantung pada model pemrograman yang Anda pilih.

Model pemrograman Python v2 memungkinkan Anda menentukan pengikatan menggunakan dekorator langsung dalam kode fungsi Python Anda. Untuk informasi selengkapnya, lihat panduan pengembang Python.

Artikel ini mendukung kedua model pemrograman.

Contoh

Fungsi C# dapat dibuat dengan menggunakan salah satu mode C# berikut:

  • Model pekerja terisolasi: Fungsi C# terkompilasi yang berjalan dalam proses pekerja yang terisolasi dari runtime. Proses pekerja terisolasi diperlukan untuk mendukung fungsi C# yang berjalan pada versi LTS dan non-LTS .NET dan .NET Framework. Ekstensi untuk fungsi proses pekerja yang terisolasi menggunakan Microsoft.Azure.Functions.Worker.Extensions.* namespace layanan.
  • Model dalam proses: Fungsi C# yang dikompilasi yang berjalan dalam proses yang sama dengan runtime Functions. Dalam variasi model ini, Functions dapat dijalankan menggunakan scripting C#, yang didukung terutama untuk pengeditan portal C#. Ekstensi untuk fungsi dalam proses menggunakan Microsoft.Azure.WebJobs.Extensions.* namespace layanan.

Penting

Dukungan akan berakhir untuk model dalam proses pada 10 November 2026. Kami sangat menyarankan Agar Anda memigrasikan aplikasi Anda ke model pekerja yang terisolasi untuk dukungan penuh.

Contoh berikut adalah fungsi C# yang berjalan dalam proses pekerja yang terisolasi dan menggunakan pemicu blob dengan input blob dan pengikatan blob output blob. Fungsi ini dipicu oleh pembuatan blob dalam kontainer test-samples-trigger. Fungsi ini membaca file teks dari kontainer test-samples-input dan membuat file teks baru dalam kontainer output berdasarkan nama file yang dipicu.

    public static class BlobFunction
    {
        [Function(nameof(BlobFunction))]
        [BlobOutput("test-samples-output/{name}-output.txt")]
        public static string Run(
            [BlobTrigger("test-samples-trigger/{name}")] string myTriggerItem,
            [BlobInput("test-samples-input/sample1.txt")] string myBlob,
            FunctionContext context)
        {
            var logger = context.GetLogger("BlobFunction");
            logger.LogInformation("Triggered Item = {myTriggerItem}", myTriggerItem);
            logger.LogInformation("Input Item = {myBlob}", myBlob);

            // Blob Output
            return "blob-output content";
        }
    }
}

Bagian ini berisi contoh-contoh berikut:

Pemicu HTTP, cari nama blob dari string kueri

Contoh berikut menunjukkan fungsi Java yang menggunakan anotasi HttpTrigger untuk menerima parameter yang berisi nama file dalam kontainer penyimpanan blob. Anotasi BlobInput kemudian membaca file dan meneruskan kontennya ke fungsi sebagai byte[].

  @FunctionName("getBlobSizeHttp")
  @StorageAccount("Storage_Account_Connection_String")
  public HttpResponseMessage blobSize(
    @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,
    final ExecutionContext context) {
      // 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();
  }

Pemicu antrean, terima nama blob dari pesan antrean

Contoh berikut menunjukkan fungsi Java yang menggunakan anotasi QueueTrigger untuk menerima pesan yang berisi nama file dalam kontainer penyimpanan blob. Anotasi BlobInput kemudian membaca file dan meneruskan kontennya ke fungsi sebagai byte[].

  @FunctionName("getBlobSize")
  @StorageAccount("Storage_Account_Connection_String")
  public void blobSize(
    @QueueTrigger(
      name = "filename", 
      queueName = "myqueue-items-sample") 
    String filename,
    @BlobInput(
      name = "file", 
      dataType = "binary", 
      path = "samples-workitems/{queueTrigger}") 
    byte[] content,
    final ExecutionContext context) {
      context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
  }

Dalam pustaka runtime fungsi Java, gunakan anotasi @BlobInput pada parameter yang nilainya berasal dari Cosmos DB. Anotasi ini dapat digunakan dengan jenis Java asli, POJO, atau nilai yang dapat diubah ke null menggunakan Optional<T>.

Contoh berikut menunjukkan fungsi TypeScript yang dipicu antrean yang membuat salinan blob. Fungsi ini dipicu oleh pesan antrean yang berisi nama blob untuk disalin. Blob baru bernama {originalblobname}-Copy.

import { app, input, InvocationContext, output } from '@azure/functions';

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<unknown> {
    return context.extraInputs.get(blobInput);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: storageQueueTrigger1,
});

Contoh berikut menunjukkan fungsi JavaScript yang dipicu antrean yang membuat salinan blob. Fungsi ini dipicu oleh pesan antrean yang berisi nama blob untuk disalin. Blob baru bernama {originalblobname}-Copy.

const { app, input, output } = require('@azure/functions');

const blobInput = input.storageBlob({
    path: 'samples-workitems/{queueTrigger}',
    connection: 'MyStorageConnectionAppSetting',
});

const blobOutput = output.storageBlob({
    path: 'samples-workitems/{queueTrigger}-Copy',
    connection: 'MyStorageConnectionAppSetting',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [blobInput],
    return: blobOutput,
    handler: (queueItem, context) => {
        return context.extraInputs.get(blobInput);
    },
});

Contoh berikut menunjukkan pengikatan input blob, ditentukan dalam file function.json, yang membuat data blob yang masuk tersedia untuk fungsi PowerShell.

Berikut konfigurasi json:

{
  "bindings": [
    {
      "name": "InputBlob",
      "type": "blobTrigger",
      "direction": "in",
      "path": "source/{name}",
      "connection": "AzureWebJobsStorage"
    }
  ]
}

Berikut kode fungsinya:

# Input bindings are passed in via param block.
param([byte[]] $InputBlob, $TriggerMetadata)

Write-Host "PowerShell Blob trigger: Name: $($TriggerMetadata.Name) Size: $($InputBlob.Length) bytes"

Contoh ini menggunakan jenis SDK untuk langsung mengakses objek yang mendasar BlobClient yang disediakan oleh pengikatan input penyimpanan Blob:

import logging

import azure.functions as func
import azurefunctions.extensions.bindings.blob as blob

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)
@app.route(route="file")
@app.blob_input(
    arg_name="client", path="PATH/TO/BLOB", connection="AzureWebJobsStorage"
)
def blob_input(req: func.HttpRequest, client: blob.BlobClient):
    logging.info(
        f"Python blob input function processed blob \n"
        f"Properties: {client.get_blob_properties()}\n"
        f"Blob content head: {client.download_blob().read(size=1)}"
    )
    return "ok"

Untuk contoh penggunaan jenis SDK lainnya, lihat ContainerClient sampel dan StorageStreamDownloader .

Untuk mempelajari selengkapnya, termasuk cara mengaktifkan pengikatan jenis SDK di proyek Anda, lihat Pengikatan jenis SDK.

Kode membuat salinan blob.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="BlobOutput1")
@app.route(route="file")
@app.blob_input(arg_name="inputblob",
                path="sample-workitems/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
@app.blob_output(arg_name="outputblob",
                path="newblob/test.txt",
                connection="<BLOB_CONNECTION_SETTING>")
def main(req: func.HttpRequest, inputblob: str, outputblob: func.Out[str]):
    logging.info(f'Python Queue trigger function processed {len(inputblob)} bytes')
    outputblob.set(inputblob)
    return "ok"

Atribut

Pustaka C# proses dalam proses dan terisolasi menggunakan atribut untuk menentukan fungsi. Skrip C# sebagai gantinya menggunakan file konfigurasi function.json seperti yang dijelaskan dalam panduan pembuatan skrip C#.

Proses pekerja terisolasi mendefinisikan pengikatan input dengan menggunakan BlobInputAttribute atribut, yang mengambil parameter berikut:

Parameter Deskripsi
BlobPath Jalan menuju blob.
Koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Blob Azure. Lihat Koneksi.

Ketika Anda mengembangkan secara lokal, tambahkan pengaturan aplikasi di file local.settings.json dalam koleksi Values.

Dekorator

Hanya berlaku untuk model pemrograman Python v2.

Untuk fungsi Python v2 yang ditentukan menggunakan dekorator, properti berikut pada blob_input dekorator dan blob_output menentukan pemicu Blob Storage:

Properti Deskripsi
arg_name Nama variabel yang mewakili blob dalam kode fungsi.
path Jalur ke blob Untuk blob_input dekorator, itu adalah blob yang dibaca. blob_output Untuk dekorator, itu adalah output atau salinan blob input.
connection Akun penyimpanan string koneksi.
data_type Untuk bahasa yang diketik secara dinamis, menentukan jenis data yang mendasarinya. Kemungkinan nilainya adalah string, binary, atau stream. Untuk lebih jelasnya, lihat konsep pengikatan dan pemicu.

Untuk fungsi Python yang ditentukan dengan menggunakan function.json, lihat bagian Konfigurasi .

Anotasi

Atribut @BlobInputmemberi Anda akses ke blob yang memicu fungsi. Jika Anda menggunakan array byte dengan atribut, atur dataType ke binary. Lihat contoh input untuk detailnya.

Konfigurasi

Hanya berlaku untuk model pemrograman Python v1.

Tabel berikut menjelaskan properti yang bisa Anda atur pada objek yang options diteruskan ke input.storageBlob() metode .

Properti Deskripsi
jalan Jalan menuju blob.
koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Blob Azure. Lihat Koneksi.

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json.

Properti function.json Deskripsi
jenis Harus diatur ke blob.
arah Harus diatur ke in. Pengecualian di bagian penggunaan.
nama Nama variabel yang mewakili blob dalam kode fungsi.
jalan Jalan menuju blob.
koneksi Nama pengaturan aplikasi atau koleksi pengaturan yang menentukan cara terhubung ke Blob Azure. Lihat Koneksi.
dataType Untuk bahasa yang diketik secara dinamis, menentukan jenis data yang mendasarinya. Kemungkinan nilainya adalah string, binary, atau stream. Untuk lebih jelasnya, lihat konsep pengikatan dan pemicu.

Lihat Bagian contoh untuk contoh lengkapnya.

Penggunaan

Jenis pengikatan yang didukung oleh input Blob bergantung pada versi paket ekstensi dan modalitas C# yang digunakan di aplikasi fungsi Anda.

Saat Anda ingin fungsi memproses satu blob, pengikatan input blob dapat mengikat ke jenis berikut:

Tipe Deskripsi
string Konten blob sebagai string. Gunakan saat konten blob adalah teks sederhana.
byte[] Byte konten blob.
Jenis yang bisa diserialisasikan JSON Saat blob berisi data JSON, Functions mencoba mendeserialisasi data JSON ke dalam jenis objek CLR (POCO) yang berusia biasa.
Aliran1 Aliran input konten blob.
BlobClient1,
BlockBlobClient1,
PageBlobClient1,
TambahkanBlobClient1,
BlobBaseClient1		 Klien yang terhubung ke blob. Set jenis ini menawarkan kontrol paling besar untuk memproses blob dan dapat digunakan untuk menulis kembali jika koneksi memiliki izin yang memadai.

Saat Anda ingin fungsi memproses beberapa blob dari kontainer, pengikatan input blob dapat mengikat ke jenis berikut:

Tipe Deskripsi
T[] atau List<T> di mana T adalah salah satu jenis pengikatan input blob tunggal Array atau daftar beberapa blob. Setiap entri mewakili satu blob dari kontainer. Anda juga dapat mengikat antarmuka apa pun yang diterapkan oleh jenis ini, seperti IEnumerable<T>.
BlobContainerClient1 Klien yang terhubung ke kontainer. Jenis ini menawarkan kontrol paling besar untuk memproses kontainer dan dapat digunakan untuk menulis ke kontainer jika koneksi memiliki izin yang memadai.

1 Untuk menggunakan jenis ini, Anda perlu mereferensikan Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 atau yang lebih baru dan dependensi umum untuk pengikatan jenis SDK.

Mengikat ke string, atau Byte[] hanya direkomendasikan jika ukuran blobnya kecil. Hal ini direkomendasikan karena seluruh konten blob dimuat ke dalam memori. Untuk sebagian besar blob, gunakan jenis Stream atau BlobClient. Untuk informasi selengkapnya, lihat Konkurensi dan penggunaan memori.

Jika Anda mendapatkan pesan kesalahan saat mencoba mengikat ke salah satu jenis Storage SDK, pastikan Anda memiliki referensi ke versi Storage SDK yang benar.

Anda juga dapat menggunakan StorageAccountAttribute untuk menentukan akun penyimpanan yang akan digunakan. Anda dapat menentukan koneksi ketika Anda perlu menggunakan akun penyimpanan yang berbeda dari fungsi lain di pustaka. Konstruktor menggunakan nama pengaturan aplikasi yang berisi string koneksi penyimpanan. Atribut dapat diterapkan pada parameter, metode, atau tingkat kelas. Contoh berikut menunjukkan tingkat kelas dan tingkat metode:

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

Akun penyimpanan yang akan digunakan ditentukan dalam urutan berikut:

  • Properti BlobTrigger milik atribut Connection.
  • Atribut StorageAccount yang diterapkan ke parameter yang sama dengan atribut BlobTrigger.
  • Atribut StorageAccount yang diterapkan ke fungsi.
  • StorageAccountAtribut yang diterapkan ke kelas.
  • Akun penyimpanan default untuk aplikasi fungsi, yang ditentukan dalam pengaturan aplikasi AzureWebJobsStorage.

Atribut @BlobInputmemberi Anda akses ke blob yang memicu fungsi. Jika Anda menggunakan array byte dengan atribut, atur dataType ke binary. Lihat contoh input untuk detailnya.

Akses data blob dengan menggunakan context.extraInputs.get().

Mengakses data blob melalui parameter yang cocok dengan nama yang ditunjuk oleh parameter pengikatan dalam file function.json.

Akses data blob melalui parameter yang diketik sebagai InputStream. Lihat contoh input untuk detailnya.

Functions juga mendukung pengikatan jenis Python SDK untuk penyimpanan Azure Blob, yang memungkinkan Anda bekerja dengan data blob menggunakan jenis SDK yang mendasar ini:

Penting

Dukungan jenis SDK untuk Python saat ini dalam pratinjau dan hanya didukung untuk model pemrograman Python v2. Untuk informasi selengkapnya, lihat Jenis SDK di Python.

Koneksi

Properti connection adalah referensi ke konfigurasi lingkungan yang menentukan bagaimana aplikasi harus terhubung ke Azure Blobs. Ini mungkin menentukan:

Jika nilai yang dikonfigurasi adalah kecocokan persis untuk pengaturan tunggal dan kecocokan awalan untuk pengaturan lainnya, kecocokan persis akan digunakan.

String koneksi

Untuk mendapatkan string koneksi, ikuti langkah-langkah yang ditunjukkan di Mengelola kunci akses akun penyimpanan. String koneksi harus untuk akun penyimpanan serba-guna, bukan akun penyimpanan Blob.

String koneksi ini harus disimpan dalam pengaturan aplikasi dengan nama yang cocok dengan nilai yang ditentukan oleh properti connection konfigurasi pengikatan.

Jika nama pengaturan aplikasi dimulai dengan "AzureWebJobs", Anda hanya dapat menentukan sisa namanya di sini. Misalnya, jika Anda mengatur connection ke "MyStorage", runtime Functions mencari pengaturan aplikasi yang bernama "MyStorage". Jika Anda membiarkan connection kosong, runtime bahasa umum Functions menggunakan string koneksi Storage default di pengaturan aplikasi yang bernama AzureWebJobsStorage.

Koneksi berbasis identitas

Jika Anda menggunakan ekstensi versi 5.x atau yang lebih tinggi (bundel 3.x atau lebih tinggi untuk tumpukan bahasa non-.NET), alih-alih menggunakan string koneksi dengan rahasia, Anda dapat meminta aplikasi menggunakan identitas Microsoft Entra. Untuk menggunakan identitas, Anda menentukan pengaturan di bawah awalan umum yang memetakan ke connection properti dalam konfigurasi pemicu dan pengikatan.

Jika Anda mengatur connection ke "AzureWebJobsStorage", lihat Menyambungkan ke penyimpanan host dengan identitas. Untuk semua koneksi lainnya, ekstensi tersebut memerlukan properti berikut:

Properti Templat variabel lingkungan Deskripsi Contoh nilai
URI Layanan Blob <CONNECTION_NAME_PREFIX>__serviceUri1 URI sarana data dari layanan blob yang Anda sambungkan, menggunakan skema HTTPS. https://<storage_account_name>.blob.core.windows.net

1 <CONNECTION_NAME_PREFIX>__blobServiceUri dapat digunakan sebagai alias. Jika konfigurasi koneksi akan digunakan oleh pemicu blob, blobServiceUri juga harus disertai dengan queueServiceUri. Lihat bawah.

Formulir serviceUri tidak dapat digunakan saat konfigurasi koneksi keseluruhan akan digunakan di seluruh blob, antrean, dan/atau tabel. URI hanya dapat menunjuk layanan blob. Sebagai alternatif, Anda dapat menyediakan URI khusus untuk setiap layanan, sehingga memungkinkan penggunaan koneksi tunggal. Jika kedua versi disediakan, formulir multi-layanan digunakan. Untuk mengonfigurasi koneksi pada beberapa layanan, jangan gunakan <CONNECTION_NAME_PREFIX>__serviceUri, sebaiknya atur:

Properti Templat variabel lingkungan Deskripsi Contoh nilai
URI Layanan Blob <CONNECTION_NAME_PREFIX>__blobServiceUri URI sarana data dari layanan blob yang Anda sambungkan, menggunakan skema HTTPS. https://<storage_account_name>.blob.core.windows.net
URI Layanan Antrean (diperlukan untuk pemicu blob2) <CONNECTION_NAME_PREFIX>__queueServiceUri URI data plane layanan antrean menggunakan skema HTTPS. Nilai ini hanya diperlukan untuk pemicu blob. https://<storage_account_name>.queue.core.windows.net

2 Pemicu blob menangani kegagalan di beberapa percobaan ulang dengan menulis blob racun ke antrean. Dalam formulir serviceUri, koneksi AzureWebJobsStorage digunakan. Namun, saat menentukan blobServiceUri, URI layanan antrean juga harus disediakan dengan queueServiceUri. Disarankan agar Anda menggunakan layanan dari akun penyimpanan yang sama dengan layanan blob. Anda juga perlu memastikan pemicu dapat membaca dan menulis pesan dalam layanan antrean yang dikonfigurasi dengan menetapkan peran seperti Kontributor Data Antrean Penyimpanan.

Properti lain mungkin diatur untuk menyesuaikan koneksi. Lihat Properti umum untuk koneksi berbasis identitas.

Saat dihosting di layanan Azure Functions, koneksi berbasis identitas menggunakan identitas terkelola. Identitas yang ditetapkan sistem digunakan secara default, meskipun identitas yang ditetapkan pengguna dapat ditentukan dengan credential dan clientID properti. Perhatikan bahwa mengonfigurasi identitas yang ditetapkan oleh pengguna dengan ID sumber daya tidak didukung. Saat dijalankan dalam konteks lain, seperti pengembangan lokal, identitas pengembang Anda digunakan sebagai gantinya, meskipun ini dapat dikustomisasi. Lihat Pengembangan lokal dengan koneksi berbasis identitas.

Memberikan izin kepada identitas

Identitas apa pun yang digunakan harus memiliki izin untuk melakukan tindakan yang dimaksudkan. Untuk sebagian besar layanan Azure, ini berarti Anda perlu menetapkan peran di Azure RBAC, menggunakan peran bawaan atau kustom yang menyediakan izin tersebut.

Penting

Beberapa izin mungkin diekspos oleh layanan target yang tidak diperlukan untuk semua konteks. Jika memungkinkan, patuhi prinsip hak istimewa paling rendah, dengan memberikan identitas hanya hak istimewa yang diperlukan. Misalnya, jika aplikasi hanya perlu dapat membaca dari sumber data, gunakan peran yang hanya memiliki izin untuk membaca. Tidak pantas untuk menetapkan peran yang juga memungkinkan menulis ke layanan itu, karena ini akan menjadi izin yang berlebihan untuk operasi baca. Demikian pula, Anda ingin memastikan penetapan peran hanya mencakup sumber daya yang perlu dibaca.

Anda perlu membuat penetapan peran yang menyediakan akses ke kontainer blob Anda saat runtime. Peran manajemen seperti Pemilik tidak cukup. Tabel berikut menunjukkan peran bawaan yang direkomendasikan saat menggunakan ekstensi Blob Storage dalam operasi normal. Aplikasi Anda mungkin memerlukan izin lebih lanjut berdasarkan kode yang Anda tulis.

Jenis pengikatan Peran bawaan contoh
Pemicu Pemilik Data Blob Penyimpanan dan KontributorData Antrean Penyimpanan 1

Izin tambahan juga harus diberikan ke koneksi AzureWebJobsStorage.2
Pengikatan masukan Pembaca Data Blob Penyimpanan.
Pengikatan output Pemilik Data Blob Penyimpanan

1 Pemicu blob menangani kegagalan di beberapa percobaan ulang dengan menulis blob racun ke antrean pada akun penyimpanan yang ditentukan oleh koneksi.

2 Koneksi AzureWebJobsStorage digunakan secara internal untuk blob dan antrean yang mengaktifkan pemicu. Jika dikonfigurasi untuk menggunakan koneksi berbasis identitas, koneksi tersebut memerlukan izin tambahan di luar persyaratan default. Izin yang diperlukan dicakup oleh peran Pemilik Data Blob Penyimpanan, Kontributor Data Antrean Penyimpanan, dan Kontributor Akun Penyimpanan. Untuk mempelajari lebih lanjut, lihat Menyambungkan ke penyimpanan host menggunakan identitas.

Langkah berikutnya