Pola ekspresi pengikatan Azure Functions

Artikel
09/03/2023

Salah satu fitur pemicu dan pengikatan yang paling kuat adalah ekspresi pengikatan. Dalam file function.json dan dalam parameter fungsi dan kode, Anda dapat menggunakan ekspresi yang mengatasi nilai dari berbagai sumber.

Sebagian besar ekspresi diidentifikasi dengan dibungkus dalam kurung kurawal. Misalnya, dalam fungsi pemicu antrean, {queueTrigger} meresolusi ke teks pesan antrean. Jika properti path untuk pengikatan output blob adalah container/{queueTrigger} dan fungsi dipicu oleh pesan antrean HelloWorld, blob bernama HelloWorld dibuat.

Jenis ekspresi pengikatan

Pengaturan aplikasi
Nama file pemicu
Metadata pemicu
Payload JSON
GUID baru
Tanggal dan waktu saat ini

Ekspresi pengikatan - pengaturan aplikasi

Sebagai praktik terbaik, rahasia dan string koneksi harus dikelola menggunakan pengaturan aplikasi, bukan file konfigurasi. Ini membatasi akses ke rahasia ini dan membuatnya aman untuk menyimpan file seperti function.json di repositori kontrol sumber publik.

Pengaturan aplikasi juga berguna setiap kali Anda ingin mengubah konfigurasi berdasarkan lingkungan. Misalnya, di lingkungan pengujian, Anda mungkin ingin memantau antrean atau kontainer penyimpanan blob yang berbeda.

Ekspresi pengikatan pengaturan aplikasi diidentifikasi berbeda dari ekspresi pengikatan lainnya: dibungkus dengan tanda persen alih-alih kurung kurawal. Misalnya jika jalur pengikatan output blob adalah %Environment%/newblob.txt dan nilai pengaturan aplikasi Environment adalah Development, blob akan dibuat di kontainer Development.

Saat fungsi berjalan secara lokal, nilai pengaturan aplikasi berasal dari file local.settings.json.

Catatan

Properti connection pemicu dan pengikatan adalah kasus khusus dan secara otomatis menyelesaikan nilai sebagai pengaturan aplikasi, tanpa tanda persen.

Contoh berikut adalah pemicu Azure Queue Storage yang menggunakan pengaturan aplikasi %input_queue_name% untuk menentukan antrean yang akan dipicu.

{
  "bindings": [
    {
      "name": "order",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "%input_queue_name%",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    }
  ]
}

Anda dapat menggunakan pendekatan yang sama di pustaka kelas:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("%input_queue_name%")]string myQueueItem, 
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
}

Nama file pemicu

Pemicu path untuk Blob dapat menjadi pola yang memungkinkan Anda merujuk pada nama blob pemicu dalam pengikatan dan kode fungsi lainnya. Pola ini juga dapat mencakup kriteria pemfilteran yang menentukan blob mana yang dapat memicu pemanggilan fungsi.

Misalnya, dalam pengikatan pemicu gumpalan berikut, polanya path adalah sample-images/{filename}, yang membuat ekspresi pengikatan bernama filename:

{
  "bindings": [
    {
      "name": "image",
      "type": "blobTrigger",
      "path": "sample-images/{filename}",
      "direction": "in",
      "connection": "MyStorageConnection"
    },
    ...

Ekspresi filename lalu dapat digunakan dalam pengikatan output untuk menentukan nama blob yang dibuat:

    ...
    {
      "name": "imageSmall",
      "type": "blob",
      "path": "sample-images-sm/{filename}",
      "direction": "out",
      "connection": "MyStorageConnection"
    }
  ],
}

Kode fungsi memiliki akses ke nilai yang sama ini dengan menggunakan filename sebagai nama parameter:

// C# example of binding to {filename}
public static void Run(Stream image, string filename, Stream imageSmall, ILogger log)  
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
}

Kemampuan yang sama untuk menggunakan ekspresi dan pola pengikatan berlaku untuk atribut di pustaka kelas. Dalam contoh berikut, parameter konstruktor atribut adalah nilai path yang sama dengan contoh function.json sebelumnya:

[FunctionName("ResizeImage")]
public static void Run(
    [BlobTrigger("sample-images/{filename}")] Stream image,
    [Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
    string filename,
    ILogger log)
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
}

Anda juga dapat membuat ekspresi untuk bagian dari nama file. Dalam contoh berikut, fungsi hanya dipicu pada nama file yang cocok dengan pola: anyname-anyfile.csv

{
    "name": "myBlob",
    "type": "blobTrigger",
    "direction": "in",
    "path": "testContainerName/{date}-{filetype}.csv",
    "connection": "OrderStorageConnection"
}

Untuk informasi selengkapnya tentang cara menggunakan ekspresi dan pola dalam string jalur Blob, lihat referensi pengikatan blob Storage.

Metadata pemicu

Selain muatan data yang disediakan oleh pemicu (seperti konten pesan antrean yang memicu fungsi), banyak pemicu yang menyediakan nilai metadata tambahan. Nilai-nilai ini dapat digunakan sebagai parameter input dalam C# dan F# atau properti pada objek context.bindings di JavaScript.

Misalnya, pemicu penyimpanan Azure Queue mendukung properti berikut:

QueueTrigger - memicu konten pesan jika string valid
DequeueCount
ExpirationTime
Id
InsertionTime
NextVisibleTime
PopReceipt

Nilai metadata ini dapat diakses di properti file function.json. Misalnya, Anda menggunakan pemicu antrean dan pesan antrean berisi nama blob yang ingin Anda baca. Dalam file function.json, Anda dapat menggunakan properti metadata queueTrigger di properti blob path, seperti yang diperlihatkan dalam contoh berikut:

{
  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "queueName": "myqueue-items",
      "connection": "MyStorageConnection",
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "direction": "in",
      "connection": "MyStorageConnection"
    }
  ]
}

Detail properti metadata untuk setiap pemicu dijelaskan dalam artikel referensi terkait. Misalnya, lihat metadata pemicu antrean. Dokumentasi juga tersedia di tab Integrasikan portal, di bagian Dokumentasi di bawah area konfigurasi pengikatan.

Payload JSON

Dalam beberapa skenario, Anda dapat merujuk ke properti payload pemicu dalam konfigurasi untuk pengikatan lain dalam fungsi yang sama dan dalam kode fungsi. Ini mengharuskan payload pemicu adalah JSON dan lebih kecil dari ambang batas khusus untuk setiap pemicu. Biasanya, ukuran payload harus kurang dari 100MB, tetapi Anda harus memeriksa konten referensi untuk setiap pemicu. Menggunakan properti payload pemicu dapat memengaruhi performa aplikasi Anda, dan memaksa jenis parameter pemicu menjadi jenis sederhana seperti string atau jenis objek kustom yang mewakili data JSON. Ini tidak dapat digunakan dengan aliran, klien, atau jenis SDK lainnya.

Contoh berikut menunjukkan file function.json untuk fungsi webhook yang menerima nama blob di JSON: {"BlobName":"HelloWorld.txt"}. Pengikatan input Blob membaca blob, dan pengikatan output HTTP mengembalikan konten blob dalam respons HTTP. Perhatikan bahwa pengikatan input Blob mendapatkan nama blob dengan merujuk langsung ke properti BlobName ("path": "strings/{BlobName}")

{
  "bindings": [
    {
      "name": "info",
      "type": "httpTrigger",
      "direction": "in",
      "webHookType": "genericJson"
    },
    {
      "name": "blobContents",
      "type": "blob",
      "direction": "in",
      "path": "strings/{BlobName}",
      "connection": "AzureWebJobsStorage"
    },
    {
      "name": "res",
      "type": "http",
      "direction": "out"
    }
  ]
}

Agar ini berfungsi di C# dan F#, Anda memerlukan kelas yang menentukan bidang yang akan dideserialisasi, seperti dalam contoh berikut:

using System.Net;
using Microsoft.Extensions.Logging;

public class BlobInfo
{
    public string BlobName { get; set; }
}
  
public static HttpResponseMessage Run(HttpRequestMessage req, BlobInfo info, string blobContents, ILogger log)
{
    if (blobContents == null) {
        return req.CreateResponse(HttpStatusCode.NotFound);
    } 

    log.LogInformation($"Processing: {info.BlobName}");

    return req.CreateResponse(HttpStatusCode.OK, new {
        data = $"{blobContents}"
    });
}

Dalam JavaScript, deserialisasi JSON secara otomatis dilakukan.

module.exports = async function (context, info) {
    if ('BlobName' in info) {
        context.res = {
            body: { 'data': context.bindings.blobContents }
        }
    }
    else {
        context.res = {
            status: 404
        };
    }
}

Notasi titik

Jika beberapa properti dalam payload JSON Anda merupakan objek properti, Anda dapat merujuk langsung dengan menggunakan notasi titik (.). Notasi ini tidak berfungsi untuk pengikatan penyimpanan Azure Cosmos DB atau Table .

Misalnya, anggap JSON Anda terlihat seperti ini:

{
  "BlobName": {
    "FileName":"HelloWorld",
    "Extension":"txt"
  }
}

Anda dapat merujuk langsung ke FileName sebagai BlobName.FileName. Dengan format JSON ini, berikut tampilan properti path dalam contoh sebelumnya:

"path": "strings/{BlobName.FileName}.{BlobName.Extension}",

Dalam C#, Anda akan membutuhkan dua kelas:

public class BlobInfo
{
    public BlobName BlobName { get; set; }
}
public class BlobName
{
    public string FileName { get; set; }
    public string Extension { get; set; }
}

Buat GUID

Ekspresi pengikatan {rand-guid} membuat GUID. Jalur blob berikut dalam file function.json membuat blob dengan nama seperti 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{rand-guid}.txt"
}

Waktu saat ini

Ekspresi pengikatan DateTime diresolusi ke DateTime.UtcNow. Jalur blob berikut dalam file function.json membuat blob dengan nama seperti 2018-02-16T17-59-55Z.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{DateTime}.txt"
}

Pengikatan pada runtime

Dalam C# dan bahasa .NET lainnya, Anda dapat menggunakan pola pengikatan imperatif, alih-alih pengikatan deklaratif di function.json dan atribut. Pengikatan imperatif berguna ketika parameter pengikatan perlu dihitung pada runtime alih-alih waktu desain. Untuk mempelajari lebih lanjut, lihat referensi pengembang C# atau referensi pengembang skrip C#.

Langkah berikutnya

Menggunakan nilai pengembalian Azure Function

Share via