Latihan - Menulis data dengan pengikatan output

15 menit

Dalam latihan sebelumnya, kita menerapkan skenario untuk mencari marka buku di database Azure Cosmos DB. Kita mengonfigurasi input yang mengikat untuk membaca data dari koleksi bookmark kita. Akan tetapi, kita bisa berbuat lebih banyak. Mari kita perluas skenarionya untuk menyertakan tulisan. Pertimbangkan diagram alur berikut:

Diagram alur keputusan yang mengilustrasikan proses penambahan bookmark di back-end Azure Cosmos DB dan mengembalikan respons.

Dalam skenario ini, kami menerima permintaan untuk menambahkan marka buku ke koleksi kami. Permintaan meneruskan kunci yang diinginkan, atau ID, bersama dengan URL bookmark. Seperti yang Anda lihat di diagram alur, kami merespons dengan kesalahan jika kunci sudah ada di ujung belakang kami.

Jika kunci yang diteruskan kepada kami tidak ditemukan, kami menambahkan marka buku baru ke database kami. Kita bisa saja berhenti di sana, tapi mari kita lakukan sedikit lebih banyak.

Perhatikan langkah lain dalam diagram alur? Sejauh ini, kami tidak melakukan banyak hal dengan data yang kami terima dalam hal pemrosesan. Kita memindahkan apa yang kita terima ke dalam database. Namun, dalam solusi nyata, kita mungkin akan memproses data dengan cara tertentu. Kita dapat melakukan semua pemrosesan dalam fungsi yang sama, tetapi dalam latihan ini, kita menunjukkan pola yang membongkar pemrosesan lebih lanjut ke komponen atau bagian logika bisnis lain.

Apa yang mungkin menjadi contoh yang baik dari pemindahan pekerjaan dalam skenario marka buku kami? Nah, bagaimana jika kita mengirim bookmark baru ke sebuah layanan pembuatan kode QR? Layanan tersebut, pada gilirannya, akan menghasilkan kode QR untuk URL, menyimpan gambar di Blob Storage, serta menambahkan alamat gambar QR kembali ke entri di dalam koleksi bookmark. Memanggil layanan untuk menghasilkan gambar QR memakan waktu. Jadi daripada menunggu hasilnya, kami menyerahkan tugas ke fungsi dan membiarkannya menyelesaikan tugas ini secara asinkron.

Sebagaimana Azure Functions yang mendukung pengikatan input untuk berbagai sumber integrasi, Azure Functions juga memiliki kumpulan template untuk pengikatan output guna memudahkan Anda menulis data ke sumber data. Pengikatan output juga dikonfigurasi dalam file function.json. Seperti yang Anda lihat dalam latihan ini, kita dapat mengonfigurasi fungsi kita untuk bekerja dengan beberapa sumber data dan layanan.

Penting

Latihan ini dibangun di atas sumber daya kotak pasir dan sumber daya yang Anda buat di unit sebelumnya; khususnya, database Azure Cosmos DB, marka buku, dan pengikatan input. Jika Anda belum menyelesaikan latihan di unit sebelumnya, Anda tidak akan bisa menyelesaikan latihan ini.

Membuat fungsi yang dipicu HTTP

Di portal Azure, buka aplikasi fungsi yang Anda buat dengan memilih nama aplikasi fungsi di jalur breadcrumb di bagian atas halaman fungsi HttpTrigger2.
Di tab Fungsi pada halaman Gambaran Umum , Anda harus memiliki fungsi pemicu HTTP yang Anda buat.
Pilih Buat pada tab Fungsi . Panel Buat fungsi muncul.
Di bawah bagian Pilih templat , pilih pemicu HTTP, lalu pilih Berikutnya. Terima default pada tab Detail templat dan pilih Buat. Panel Ringkasan untuk fungsi HttpTrigger3 muncul.

Menambahkan sebuah pengikatan input Azure Cosmos DB

Mari tambahkan pengikatan input Azure Cosmos DB lainnya.

Di menu Fungsi HttpTrigger3, pilih Integrasi. Panel Integrasi akan muncul.
Dalam kotak Pemicu dan input , pilih Tambahkan input. Panel Buat Input akan muncul.
Dalam daftar dropdown Jenis Pengikatan, pilih Azure Cosmos DB.
Pengaturan koneksi akun Cosmos DB harus diisi sebelumnya dengan koneksi yang Anda buat di latihan sebelumnya.

Jika Anda tidak melihat koneksi Anda dalam daftar, ikuti langkah-langkah ini untuk membuat koneksi baru.
1. Di bagian Detail Azure Cosmos DB, pada pengaturan Koneksi akun Azure Cosmos DB, pilih tautan Baru.
2. Saat kotak dialog koneksi New Cosmos DB muncul, pilih OK untuk membuat koneksi. Koneksi akun Cosmos DB baru dibuat.

Masukkan nilai berikut untuk setelan lain di panel ini. Kapan saja, untuk mempelajari selengkapnya tentang tujuan pengaturan, Anda dapat memilih ikon informasi di sebelah kanannya.

Pengaturan	Nilai	Deskripsi
Nama parameter dokumen	`bookmark`	Nama yang digunakan untuk mengidentifikasi pengikatan ini di dalam kode Anda.
Nama database	`func-io-learn-db`	Database yang akan digunakan. Nilai ini merupakan nama database yang kita tetapkan sebelumnya dalam pelajaran ini.
Nama Koleksi	`Bookmarks`	Nama koleksi tempat data dibaca. Kita mendefinisikan setelan ini sebelumnya dalam pelajaran.
ID Dokumen	`{id}`	Tambahkan `{id}` untuk menggunakan ekspresi pengikatan yang benar dan terima parameter yang diteruskan dalam string kueri.
Kunci partisi	`{id}`	Sekali lagi, tambahkan `{id}` untuk menggunakan ekspresi pengikatan yang benar dan terima parameter yang diteruskan dalam string kueri.
Kueri SQL (opsional)	Biarkan kosong	Kami hanya mengambil satu item pada satu waktu berdasarkan ID. Jadi, memfilter dengan pengaturan Dokumen lebih baik daripada menggunakan Kueri SQL dalam instans ini. Kita dapat membuat SQL Query untuk mengembalikan satu entri (`SELECT * from b where b.ID = /id`). Kueri tersebut memang akan menampilkan sebuah item, tetapi ia akan mengembalikannya ke dalam koleksi item. Kode kita harus memanipulasi koleksi yang tidak perlu. Gunakan pendekatan SQL Query pada saat Anda ingin mendapatkan beberapa dokumen.

Seperti pengikatan input yang dibuat di latihan sebelumnya, kita ingin mencari marka buku dengan ID tertentu, jadi kita mengikat ID Dokumen yang diterima fungsi kita dalam string kueri ke pengikatan, yang dikenal sebagai ekspresi pengikatan. Pemicu fungsi adalah permintaan HTTP yang menggunakan string kueri untuk menentukan ID yang akan dicari. Pengikatan mengembalikan 0 (tidak ditemukan) atau 1 (ditemukan) dokumen.

Pilih Tambahkan untuk menyimpan konfigurasi pengikatan input.

Kita sekarang memiliki pengikatan input Azure Cosmos DB. Mari tambahkan pengikatan output sehingga kita dapat menulis entri baru ke kumpulan kita.

Menambahkan pengikatan output Azure Cosmos DB

Di panel Integrasi untuk HttpTrigger3, di kotak Output, pilih Tambahkan output. Panel Buat Output akan muncul.
Di bagian Jenis Pengikatan, dari daftar dropdown, pilih Azure Cosmos DB.
Pengaturan koneksi akun Cosmos DB harus diisi sebelumnya dengan koneksi yang Anda buat sebelumnya. Jika tidak, perluas daftar dropdown dan pilih koneksi yang Anda tetapkan untuk pengikatan input HttpTrigger3.

Masukkan nilai berikut untuk setelan yang tersisa untuk pengikatan output.

Pengaturan	Nilai	Deskripsi
Nama parameter dokumen	`newbookmark`	Nama yang digunakan untuk mengidentifikasi pengikatan ini di dalam kode Anda. Parameter ini digunakan untuk menulis sebuah entri bookmark baru.
Nama database	`func-io-learn-db`	Database yang akan digunakan. Nilai ini merupakan nama database yang kita tetapkan sebelumnya dalam pelajaran ini.
Nama Koleksi	`Bookmarks`	Nama koleksi tempat data dibaca. Nilai ini adalah nama kontainer yang kita tentukan sebelumnya dalam pelajaran.
Kunci partisi	`/id`	Tambahkan kunci partisi yang kita tentukan ketika kita membuat kontainer Bookmarks Azure Cosmos DB sebelumnya. Kunci yang dimasukkan di sini (ditentukan dalam konfigurasi pengikatan input `<key>`) harus cocok dengan yang ada di kontainer.

Pilih Tambahkan untuk menyimpan konfigurasi pengikatan output ini.

Sekarang kita memiliki ikatan untuk membaca dari kumpulan kita, dan ikatan untuk menulisnya.

Menambahkan pengikatan output Azure Queue Storage

Azure Queue Storage adalah layanan untuk menyimpan pesan yang dapat diakses dari mana saja di dunia. Ukuran satu pesan bisa sebanyak 64 KB, dan antrean dapat berisi jutaan pesan--hingga total kapasitas akun penyimpanan tempat antrean ditentukan. Diagram berikut menunjukkan, pada tingkat tinggi, bagaimana antrean digunakan dalam skenario kita.

Ilustrasi yang menunjukkan antrean penyimpanan dengan fungsi mendorong dan fungsi lain memunculkan pesan.

Dalam contoh ini, Anda melihat bahwa fungsi bernama add-bookmark menambahkan pesan ke antrean, dan fungsi lain bernama gen-qr-code mengeluarkan pesan dari antrean yang sama, dan memproses permintaan. Karena kami menulis, atau mendorong, pesan ke antrean dari add-bookmark, kami menambahkan pengikatan output baru ke solusi Anda.

Mari kita buat pengikatan melalui portal.

Pada panel Integrasi untuk fungsi Anda, di kotak Output, pilih Tambahkan Output. Panel Buat Output akan muncul.
Dalam daftar dropdown Jenis Pengikatan, pilih Azure Queue Storage.

Jika muncul pesan yang meminta Anda untuk memasang ekstensi Microsoft.Azure.WebJobs.Extensions.Storage, pilih instal dan tunggu sampai selesai.

Selanjutnya, kami menyiapkan koneksi akun penyimpanan, tempat antrean kami dihosting.

Di bawah Koneksi akun penyimpanan, pilih Baru. Kotak dialog Koneksi Akun Penyimpanan Baru akan muncul.
Di awal modul ini, saat Anda membuat aplikasi fungsi, akun penyimpanan juga dibuat untuk Anda. Pilih dari daftar dropdown, lalu pilih OK.

Pengaturan Koneksi akun penyimpanan diisi dengan nama koneksi.

Meskipun kita dapat mempertahankan nilai default, mari ubah beberapa pengaturan untuk memberi lebih banyak arti pada properti yang tersisa.

Selesaikan pengaturan di panel Buat Output, dengan mengganti nilai lama berikut dengan nilai baru:

Pengaturan	Nilai lama	Nilai baru	Deskripsi
Nama parameter pesan	outputQueueItem	newmessage	Properti pengikatan yang kami gunakan dalam kode.
Nama antrean	outqueue	bookmarks-post-process	Nama antrean tempat kita menempatkan marka buku sehingga fungsi lain dapat memprosesnya lebih lanjut.

Pilih Tambahkan untuk menyimpan konfigurasi output Anda untuk Azure Queue Storage.

Perbarui implementasi fungsi

Sekarang kita telah menyiapkan semua pengikatan. Saatnya untuk menggunakannya dalam fungsi kita.

Untuk membuka file index.js di editor kode, pilih fungsi Anda, HttpTrigger3.
Di menu, pilih Kode + Uji. Panel Kode + Uji akan muncul untuk fungsi Anda.

Ganti semua kode di file index.js dengan kode dari cuplikan berikut, lalu di bilah perintah, pilih Simpan.

module.exports = function (context, req) {

    var bookmark = context.bindings.bookmark;
    if(bookmark){
            context.res = {
            status: 422,
            body : "Bookmark already exists.",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    else {
        
        // Create a JSON string of our bookmark.
        var bookmarkString = JSON.stringify({ 
            id: req.body.id,
            url: req.body.url
        });

        // Write this bookmark to our database.
        context.bindings.newbookmark = bookmarkString;

        // Push this bookmark onto our queue for further processing.
        context.bindings.newmessage = bookmarkString;

        // Tell the user all is well.
        context.res = {
            status: 200,
            body : "bookmark added!",
            headers: {
            'Content-Type': 'application/json'
            }
        };
    }
    context.done();
};

Mari kita uraikan apa yang dilakukan kode ini:

Karena fungsi ini mengubah data kita, kita mengharapkan permintaan HTTP menjadi POST, dan data bookmark menjadi bagian dari badan permintaan.
Pengikatan input Azure Cosmos DB kita mencoba mengambil dokumen, atau bookmark, dengan menggunakan id yang kita terima. Jika pengikatan input tersebut menemukan entri, objek bookmark diatur. Pemeriksaan kondisi if(bookmark) untuk melihat apakah entri ditemukan.
Menambahkan ke database sempit seperti mengatur context.bindings.newbookmark parameter pengikatan ke entri bookmark baru, yang kami buat sebagai string JSON.
Mem-posting pesan ke antrean kita semudah mengatur parameter context.bindings.newmessage.

Catatan

Satu-satunya tugas yang Anda lakukan adalah untuk membuat pengikatan antrean. Anda tidak pernah membuat antrean secara eksplisit. Anda sedang menyaksikan kekuatan pengikatan! Seperti yang dinyatakan oleh pemberitahuan berikut ini, antrean akan secara otomatis dibuat untuk Anda jika tidak ada.

Cuplikan layar memperlihatkan pesan bahwa antrean akan dibuat secara otomatis. .

Pilih function.json dari daftar dropdown di jalur Anda <functionapp> \ HttpTrigger3 \ dan buat perubahan berikut:
1. Ubah semua instans menjadi "collectionName" "containerName".
2. Ubah semua instans menjadi "connectionStringSetting" "connection".
3. Hapus referensi ke "methods": [].

File function.json akhir Anda harus menyerupai kode ini.

{
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "name": "bookmark",
      "direction": "in",
      "type": "cosmosDB",
      "partitionKey": "{id}",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB",
      "id": "{id}"
    },
    {
      "name": "newbookmark",
      "direction": "out",
      "type": "cosmosDB",
      "partitionKey": "/id",
      "databaseName": "func-io-learn-db",
      "containerName": "Bookmarks",
      "connection": "your-database_DOCUMENTDB"
    },
    {
      "name": "newmessage",
      "direction": "out",
      "type": "queue",
      "queueName": "bookmarks-post-process",
      "connection": "your-storage-account_STORAGE"
    }
  ]
}

Di bilah perintah, pilih Simpan.

Jadi, itu saja. Mari kita lihat pekerjaan kita berjalan di bagian berikutnya.

Untuk membuka file run.ps1 di editor kode, pilih fungsi HttpTrigger3 Anda dari breadcrumb di bagian atas panel.
Di menu Fungsi, di bawah Pengembang, pilih Kode + Pengujian. Panel Kode + Uji untuk fungsi HttpTrigger3 Anda muncul, menampilkan konten default run.ps1.

Ganti konten dalam file dengan kode berikut.

using namespace System.Net

param($Request, $bookmark, $TriggerMetadata)

if ($bookmark) {
    $status = 422
    $body = "Bookmark already exists."
}
else {
    $newBookmark = @{ id = $Request.Body.id; url = $Request.Body.url }

    Push-OutputBinding -Name newbookmark -Value $newBookmark

    Push-OutputBinding -Name newmessage -Value $newBookmark

    $status = [HttpStatusCode]::OK
    $body = "bookmark added!"
}

Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = $status
    Body = $body
    ContentType = "application/json"
})

Pilih Simpan di bilah perintah. Koneksi dibuat, dan sesi file log terbuka.

Mari kita uraikan apa yang dilakukan kode ini:

Karena fungsi ini mengubah data kita, kita mengharapkan permintaan HTTP menjadi POST, dan data bookmark menjadi bagian dari badan permintaan.
Pengikatan input Azure Cosmos DB kita mencoba mengambil dokumen, atau marka buku, dengan menggunakan id dalam permintaan. Jika pengikatan input tersebut menemukan entri, objek bookmark diatur. Pemeriksaan kondisi if ($bookmark) untuk melihat apakah entri ditemukan.
Menambahkan ke database semudah memanggil Push-OutputBinding dengan nama pengikatan output Cosmos DB (newbookmark) dan nilai objek $newBookmark.
Mem-posting pesan ke antrean kita semudah memanggil Push-OutputBinding dengan nama pengikatan output antrean (newmessage) dan nilai objek $newBookmark.

Catatan

Cuplikan layar yang menunjukkan tip alat antarmuka pengguna bahwa antrean akan dibuat secara otomatis.

Jadi, itu saja. Mari kita lihat pekerjaan kita berjalan di bagian berikutnya.

Cobalah

Sekarang kita memiliki beberapa pengikatan output, pengujian akan menjadi sedikit lebih rumit. Di unit sebelumnya, kami adalah konten untuk diuji dengan mengirim permintaan HTTP dengan string kueri, tetapi kami ingin melakukan posting HTTP kali ini. Kita juga perlu memeriksa apakah pesan membuatnya menjadi antrean.

Di panel perintah panel Kode + Uji untuk fungsi HttpTrigger3 Anda, pilih Uji/Jalankan. Sebuah panel baru muncul, dengan tab Input terbuka, seperti yang ditunjukkan pada gambar ini:
Dalam daftar drop-down Metode HTTP, verifikasi bahwa POST dipilih.

Ganti konten Isi permintaan dengan objek JSON berikut:

{
    "id": "docs",
    "url": "https://learn.microsoft.com/azure"
}

Pilih Jalankan.
Kemajuan terprogram ditampilkan di panel Log. Setelah selesai, verifikasi bahwa tab Output menampilkan "Marka buku sudah ada." di setelan konten respons HTTP.

Anda menambahkan item marka buku di Latihan - Membaca data dengan pengikatan input. Respons tersebut mengonfirmasikan bahwa var bookmark = context.bindings.bookmark JavaScript Anda berfungsi dengan benar, dan bahwa kode PowerShell Anda membuat sambungan yang sama.
Mari posting bookmark kedua ke database. Pilih tab Input.

Ganti konten Isi permintaan dengan objek JSON berikut:

{
    "id": "github",
    "url": "https://www.github.com"
}

Pilih Jalankan.
Pastikan tab Output menampilkan "marka buku ditambahkan!" di konten respons HTTP, seperti yang ditunjukkan pada cuplikan layar berikut.

Selamat! Fungsi Anda berfungsi seperti yang dirancang! Tapi, bagaimana dengan operasi antrian yang kita tambahkan ke kode? Nah, mari kita lihat apakah ada sesuatu yang ditulis untuk antrean.

Memverifikasi bahwa pesan sudah ditulis ke antrean

Antrean Azure Queue Storage di-hosting di akun penyimpanan. Anda mengonfigurasi akun penyimpanan saat Anda membuat pengikatan output.

Di bilah pencarian global portal Azure, masukkan akun penyimpanan, lalu di daftar hasil, pilih Akun penyimpanan. Panel Akun penyimpanan muncul.
Pilih akun penyimpanan yang Anda gunakan untuk mengonfigurasi pengikatan output newmessage.
Di menu Akun penyimpanan, pada bagian Penyimpanan data, pilih Antrean untuk mencantumkan antrian yang dihosting oleh akun penyimpanan ini. Pastikan antrean bookmarks-post-process tercantum, seperti yang ditunjukkan pada cuplikan layar berikut.
Pilih bookmarks-post-process untuk mencantumkan pesan yang ada dalam antrean. Jika semua berjalan sesuai rencana, maka antrean menyertakan pesan yang Anda posting saat Anda menambahkan bookmark ke database. Hal itu akan terlihat seperti berikut ini.

Dalam contoh ini, pesan diberi ID unik, dan kolom Teks pesan menampilkan marka buku Anda dalam format JSON. Tidak ada pesan untuk marka buku Azure docs yang Anda coba tambahkan karena sudah ada di database.
Anda dapat menguji fungsi lebih lanjut dengan mengubah isi permintaan di panel uji dengan set id/url baru, lalu menjalankan fungsi. Perhatikan antrean ini untuk melihat lebih banyak pesan yang datang. Anda juga dapat melihat database untuk memverifikasi bahwa entri baru ditambahkan.

Dalam latihan ini, kami memperluas pengetahuan Anda tentang pengikatan ke pengikatan output, dan menulis data ke Azure Cosmos DB Anda. Kami menambahkan pengikatan output untuk mengirim pesan ke antrean Azure. Contoh ini menunjukkan kekuatan pengikatan yang sebenarnya untuk membantu Anda membentuk dan memindahkan data dari sumber masuk ke berbagai tujuan. Kami tidak perlu menulis kode database apa pun atau mengelola string koneksi sendiri. Sebagai gantinya, kami mengonfigurasi pengikatan secara deklaratif, dan membiarkan platform menangani pengamanan koneksi, penskalaan fungsi, dan penskalaan koneksi.

Lanjutkan