Bagikan melalui

Tutorial: Mengunggah gambar ke blob Azure Storage dengan JavaScript

Dalam tutorial ini Anda akan menggunakan aplikasi web statis untuk mengunggah file langsung ke blob Azure Storage menggunakan @azure/storage-blob paket . API menghasilkan token SAS setelah pola Valet Key, yang memungkinkan Anda mendelegasikan akses terbatas dengan aman tanpa mengekspos kredensial penuh.

Perhatian

Tutorial ini menunjukkan kepada Anda cara menghosting aplikasi fungsi Anda dalam Paket Konsumsi. Saat Anda berencana untuk mengamankan koneksi dengan menggunakan Microsoft Entra ID dan identitas terkelola, Anda sebaiknya mempertimbangkan untuk menghosting aplikasi Anda dalam paket Flex Consumption . Lapisan Konsumsi Flex mengoptimalkan keamanan dengan mendukung identitas yang terkelola dan integrasi jaringan virtual.

Prasyarat

  • Langganan Azure; jika Anda belum memiliki langganan Azure, Anda dapat mendaftar untuk akun Azure gratis .
  • akun GitHub untuk melakukan fork dan push ke repositori.

Arsitektur aplikasi

Arsitektur aplikasi ini mencakup dua sumber daya Azure:

  • Azure Static Web Apps menghosting klien statis dan Azure Functions API yang ditautkan, dengan layanan yang mengelola sumber daya API secara otomatis.
  • Azure Storage untuk penyimpanan blob.

Diagram memperlihatkan bagaimana pelanggan berinteraksi dari komputer mereka untuk menggunakan situs web untuk mengunggah file ke Azure Storage secara langsung.

Langkah Deskripsi
1 Pelanggan terhubung ke situs web yang dihasilkan secara statis. Situs web ini dihosting pada Azure Static Web Apps.
2 Pelanggan menggunakan situs web tersebut, untuk memilih file yang akan diunggah. Untuk tutorial ini, kerangka kerja front-end Vite React dan file yang diunggah adalah file gambar.
3 Situs web memanggil Azure Functions API sas untuk mendapatkan token SAS berdasarkan nama file yang tepat file untuk diunggah. API tanpa server menggunakan Azure Blob Storage SDK untuk membuat token SAS. API mengembalikan URL lengkap yang akan digunakan untuk mengunggah file, yang menyertakan token SAS sebagai string kueri.
https://YOUR-STORAGE-NAME.blob.core.windows.net/YOUR-CONTAINER/YOUR-FILE-NAME?YOUR-SAS-TOKEN
4 Situs web front-end menggunakan URL token SAS untuk mengunggah file langsung ke Azure Blob Storage.

Lingkungan lokal dan lingkungan pengembangan

Tutorial ini menggunakan lingkungan berikut:

  • Pengembangan lokal dengan GitHub Codespaces atau Visual Studio Code.
  • Buat dan sebarkan dengan GitHub Actions.

Fork repositori aplikasi sampel dengan GitHub

Tutorial ini menggunakan tindakan GitHub untuk menyebarkan aplikasi sampel ke Azure. Anda memerlukan akun GitHub dan fork repositori aplikasi sampel untuk menyelesaikan penyebaran tersebut.

  1. Di browser web, gunakan tautan berikut untuk memulai fork untuk akun Anda sendiri dari repositori sampel: Azure-Samples/azure-typescript-e2e-apps.
  2. Selesaikan langkah-langkah untuk mem-fork sampel dengan cabang utama saja.

Mengonfigurasi lingkungan pengembangan

Lingkungan kontainer pengembangan tersedia dengan seluruh dependensi yang diperlukan untuk menyelesaikan setiap latihan dalam proyek ini. Anda dapat menjalankan kontainer pengembangan di GitHub Codespaces atau secara lokal menggunakan Visual Studio Code.

  • GitHub Codespaces
  • Visual Studio Code

GitHub Codespaces menjalankan kontainer pengembangan yang dikelola oleh GitHub dengan Visual Studio Code untuk Web sebagai antarmuka pengguna. Untuk lingkungan pengembangan yang paling mudah, gunakan GitHub Codespaces sehingga Anda memiliki alat dan dependensi pengembang yang benar yang telah diinstal sebelumnya untuk menyelesaikan modul pelatihan ini.

Penting

Semua akun GitHub dapat menggunakan Codespace hingga 60 jam gratis setiap bulan dengan 2 instans inti. Untuk informasi selengkapnya, lihat GitHub Codespaces bulanan yang disertakan penyimpanan dan jam inti.

  1. Di browser web, pada fork GitHub Anda dari repositori sampel, mulai proses untuk membuat GitHub Codespace baru pada cabang main di fork Anda dengan memilih tombol CODE.

    cuplikan layar GitHub tombol Codespaces untuk repositori.

  2. Pada tab Codespaces, pilih elipsi ....

    cuplikan layar GitHub tab Codespaces dengan kontrol elipsis disorot.

  3. Pilih + Baru dengan opsi untuk memilih kontainer pengembangan Codespace tertentu.

    cuplikan layar GitHub Codespaces New dengan item menu opsi disorot.

  4. Pilih opsi berikut lalu pilih Buat codespace.

    • Cabang: main
    • Konfigurasi Kontainer Dev: Tutorial: Upload file to storage with SAS Token
    • Wilayah: terima default
    • Jenis mesin: terima default

    cuplikan layar GitHub Codespaces New dengan menu opsi dengan kontainer dev berikut disorot, Tutorial: Unggah file ke penyimpanan dengan Token SAS.

  5. Tunggu hingga codespace dimulai. Proses startup ini dapat memakan waktu beberapa menit.

  6. Buka terminal baru di codespace.

    Tips

    Anda dapat menggunakan menu utama untuk menavigasi ke opsi menu Terminal lalu memilih opsi Terminal Baru.

    Cuplikan layar opsi menu codespace untuk membuka terminal baru.

  7. Periksa versi alat yang Anda gunakan dalam tutorial ini.

    node --version
npm --version
func --version

    Tutorial ini memerlukan versi berikut dari setiap alat, yang telah diinstal sebelumnya di lingkungan Anda:

    Alat Versi
    Node.js ≥ 18
    npm ≥ 9,5
    Alat inti Azure Functions ≥ 4.5098

  8. Tutup terminal.

  9. Langkah-langkah yang tersisa dalam tutorial ini berlangsung dalam konteks kontainer pengembangan ini.

Pasang dependensi

Aplikasi sampel untuk tutorial ini ada di folder azure-upload-file-to-storage. Anda tidak perlu menggunakan folder lain dalam proyek.

  1. Di Visual Studio Code, buka terminal, dan pindah ke folder proyek.

    cd azure-upload-file-to-storage

  2. Pisahkan terminal sehingga Anda memiliki dua terminal, satu untuk aplikasi klien dan satu untuk aplikasi API.

  3. Di salah satu terminal, jalankan perintah berikut untuk menginstal dependensi aplikasi API dan menjalankan aplikasi.

    cd api && npm install

  4. Di terminal lain, jalankan perintah untuk menginstal aplikasi klien .

    cd app && npm install

Membuat sumber daya penyimpanan dengan ekstensi Visual Studio

Buat sumber daya Azure Storage untuk digunakan dengan aplikasi sampel. Penyimpanan digunakan untuk:

  • Pemicu di aplikasi Azure Functions
  • Penyimpanan objek biner besar (blob)

  1. Navigasikan ke ekstensi Azure Storage.

  2. Masuk ke Azure jika perlu.

  3. Klik kanan pada langganan lalu pilih Create Resource....

    Cuplikan layar Visual Studio Code di Azure Explorer dengan menu klik kanan memperlihatkan item Buat Sumber Daya disorot.

  4. Pilih Buat Akun Penyimpanan dari daftar.

  5. Ikuti perintah menggunakan tabel berikut untuk memahami cara membuat sumber daya Storage Anda.

    Harta benda Nilai
    Masukkan nama unik global untuk aplikasi web baru. Masukkan nilai unik seperti fileuploadstor, untuk nama sumber daya Penyimpanan Anda.

    Nama unik ini adalah nama sumber daya Anda yang digunakan di bagian berikutnya. Gunakan panjang maksimum 24 karakter alfanumerik. Anda memerlukan nama akun ini untuk digunakan nanti.
    Pilih lokasi untuk sumber daya baru. Gunakan lokasi yang direkomendasikan.

  6. Saat proses pembuatan aplikasi selesai, pemberitahuan muncul dengan informasi tentang sumber daya baru.

    Cuplikan layar Visual Studio Code memperlihatkan Bilah Aktivitas Azure dan pemberitahuan bahwa akun penyimpanan berhasil dibuat.

Mengonfigurasi CORS untuk Penyimpanan

Karena browser digunakan untuk mengunggah file, akun Azure Storage perlu mengonfigurasi CORS untuk mengizinkan permintaan lintas asal. Pengaturan CORS ini digunakan untuk tutorial ini untuk menyederhanakan langkah-langkah dan tidak dimaksudkan untuk menunjukkan praktik terbaik atau keamanan. Pelajari selengkapnya tentang CORS untuk Azure Storage.

  1. Navigasikan ke ekstensi Azure Storage. Klik kanan pada sumber daya penyimpanan Anda dan pilih Buka di Portal.

  2. Di bagian Pengaturan akun penyimpanan portal Microsoft Azure, pilih Berbagi sumber daya (CORS).

  3. Gunakan properti berikut untuk mengatur CORS untuk tutorial ini.

    • Asal yang diizinkan: *
    • Metode yang diizinkan: Semua kecuali patch
    • Header yang diizinkan: *
    • Header yang diekspos: *
    • Usia maksimum: 86400

  4. Pilih Simpan.

Memberikan akses anonim ke penyimpanan

Setelah pengunggahan file, skenario tutorial memerlukan akses publik ke blob untuk dilihat. Untuk kesederhanaan, panduan ini memungkinkan akses anonim untuk file yang diunggah.

  1. Untuk mengaktifkan akses publik di portal Microsoft Azure, pilih halaman Gambaran Umum untuk akun penyimpanan Anda, di bagian Properti, pilih akses anonim Blob lalu pilih Dinonaktifkan.
  2. Pada halaman Konfigurasi, aktifkan Izinkan akses anonim Blob.

Membuat kontainer unggahan

Buat kontainer privat yang memiliki blob yang dapat dibaca secara publik.

  1. Saat masih berada di akun penyimpanan di portal Azure, di bagian Penyimpanan Data, pilih Kontainer.

  2. Pilih + Kontainer untuk membuat kontainer upload Anda dengan pengaturan berikut:

    • Nama: upload
    • Tingkat akses publik: Blob

  3. Pilih Buat.

Memberi diri Anda akses Data Blob

Saat membuat sumber daya, Anda tidak memiliki izin untuk melihat konten kontainer. Otorisasi ini dicadangkan hanya untuk peran IAM tertentu. Tambahkan akun Anda sehingga Anda dapat melihat blob dalam kontainer.

  1. Di akun penyimpanan portal Microsoft Azure, pilih Kontrol Akses (IAM).
  2. Pilih Tambahkan penetapan peran.
  3. Cari dan pilih Kontributor Data Blob Penyimpanan. Pilih Berikutnya.
  4. Pilih + Pilih anggota.
  5. Cari dan pilih akun Anda.
  6. Pilih Tinjau lalu tetapkan.
  7. Pilih kontainer lalu mengunggah kontainer. Anda harus dapat melihat bahwa tidak ada blob dalam kontainer, dan tidak ada kesalahan otorisasi.

Mendapatkan kredensial sumber daya Penyimpanan

Kredensial sumber daya Penyimpanan digunakan di aplikasi Azure Functions API untuk menyambungkan ke sumber daya Storage.

  1. Saat masih berada di portal Microsoft Azure, di bagian Keamanan + jaringan, pilih kunci akses .

  2. Salin kunci Key .

  3. Di Visual Studio Code, di folder ./workspaces/azure-typescript-e2e-apps/azure-upload-file-to-storage/api, mengganti nama file dari local.settings.json.sample menjadi local.settings.json. File diabaikan oleh Git sehingga file tersebut tidak dimasukkan ke dalam kontrol sumber.

  4. Perbarui pengaturan untuk local.settings.json menggunakan tabel berikut ini.

    Harta benda Nilai Deskripsi
    Nama_Akun_Azure_Storage Nama akun Azure Storage, misalnya: fileuploadstor. Digunakan dalam kode sumber untuk menyambungkan ke sumber daya Storage.
    Azure_Storage_AccountKey Kunci akun Azure Storage Digunakan dalam kode sumber untuk menyambungkan ke sumber daya Storage.
    AzureWebJobsStorage String koneksi untuk akun Azure Storage Digunakan oleh runtime Azure Functions untuk menyimpan status dan log.

Sepertinya Anda memasukkan kredensial akun yang sama dua kali, sekali sebagai kunci dan sekali sebagai string koneksi. Anda melakukannya, tetapi khusus untuk tutorial sederhana ini. Secara umum, aplikasi Azure Functions harus memiliki sumber daya Storage terpisah yang tidak digunakan kembali untuk tujuan lain. Saat Anda membuat sumber daya Azure Function nanti dalam tutorial, Anda tidak perlu mengatur nilai AzureWebJobsStorage untuk sumber daya cloud. Anda harus mengatur nilai Azure_Storage_AccountName dan Azure_Storage_AccountKey yang digunakan dalam kode sumber.

Menjalankan aplikasi API

Jalankan Aplikasi Fungsi untuk memastikan aplikasi berfungsi dengan benar sebelum menyebarkannya ke Azure.

  1. Di terminal aplikasi API, jalankan perintah berikut untuk memulai aplikasi API.

    npm run start

  2. Tunggu hingga aplikasi Azure Functions dimulai. Anda akan mendapatkan pemberitahuan bahwa port aplikasi Azure Functions, 7071 sekarang tersedia. Anda juga akan melihat API yang tercantum di terminal untuk aplikasi API.

    Functions:

        list: [POST,GET] http://localhost:7071/api/list

        sas: [POST,GET] http://localhost:7071/api/sas

        status: [GET] http://localhost:7071/api/status

  3. Pilih tab Port di panel bawah, lalu klik kanan port 7071 dan pilih Visibilitas Port, kemudian pilih Publik.

    Jika Anda tidak mengekspos aplikasi ini sebagai publik, Anda akan mendapatkan kesalahan saat menggunakan API dari aplikasi klien.

  4. Untuk menguji bahwa API berfungsi dan terhubung ke penyimpanan, di tab Port di panel bawah, pilih ikon bola dunia di area Alamat Lokal untuk port 7071. Ini membuka browser web menuju aplikasi fungsi.

  5. Tambahkan rute API ke bilah alamat URL: /api/sas?container=upload&file=test.png. Tidak masalah jika file belum ada dalam wadah. API membuat token SAS berdasarkan tempat Yang Anda inginkan untuk diunggah.

  6. Respons JSON akan terlihat seperti berikut ini:

    {
    "url":"https://YOUR-STORAGE-RESOURCE.blob.core.windows.net/upload/test.png?sv=2023-01-03&spr=https&st=2023-07-26T22%3A15%3A59Z&se=2023-07-26T22%3A25%3A59Z&sr=b&sp=w&sig=j3Yc..."
}

  7. Salin dasar URL API di bilah alamat browser (bukan URL token SAS di objek JSON) untuk digunakan pada langkah berikutnya. URL dasar adalah semua yang ada sebelum /api/sas. Anda akan menempelkan URL dasar ini ke dalam file variabel lingkungan aplikasi klien di bagian berikutnya.

Mengonfigurasi dan menjalankan aplikasi klien

  1. Ganti nama file ./azure-upload-file-to-storage/app/.env.sample menjadi .env.

  2. Buka file .env dan tempelkan URL dasar dari bagian sebelumnya sebagai nilai untuk VITE_API_SERVER.

    Contoh untuk lingkungan Codespace mungkin terlihat seperti VITE_API_SERVER=https://improved-space-fishstick-pgvxvxjpqgrh6qxp-7071.app.github.dev

  3. Di terminal terpisah lainnya, mulai aplikasi klien dengan perintah berikut:

    npm run dev

  4. Tunggu hingga terminal mengembalikan pemberitahuan berikut bahwa aplikasi tersedia di port 5173.

      VITE v4.4.4  ready in 410 ms

  ➜  Local:   https://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

  5. Pilih tab Port di panel bawah lalu klik kanan port 5173 dan pilih ikon globe.

  6. Sebaiknya Anda melihat aplikasi web.

    Cuplikan layar browser web memperlihatkan aplikasi web dengan tombol Pilih File yang tersedia.

  7. Berinteraksi dengan aplikasi web:

    • Pilih file gambar (*.jpg atau *.png) dari komputer lokal Anda untuk diunggah.
    • Pilih tombol Dapatkan SAS untuk meminta token SAS dari aplikasi API. Respons menunjukkan URL lengkap yang akan digunakan untuk mengunggah file ke Storage.
    • Pilih tombol Unggah untuk mengirim file gambar langsung ke Penyimpanan.

    Cuplikan layar browser web yang memperlihatkan aplikasi web dengan file gambar yang diunggah dan gambar mini file ditampilkan.

  8. Aplikasi klien dan aplikasi API berhasil bekerja sama di lingkungan pengembang dalam kontainer.

Menerapkan perubahan kode

  1. Di Visual Studio Code, buka tab Kontrol Sumber.
  2. Pilih ikon + untuk mentahapkan semua perubahan. Perubahan ini hanya boleh menyertakan file package-lock.json baru untuk folder app dan api untuk tutorial ini.

Menyebarkan aplikasi web statis ke Azure

Aplikasi Azure Functions menggunakan fitur pratinjau. Ini harus dikerahkan ke West US 2 agar berfungsi dengan baik.

  1. Di Visual Studio Code, pilih penjelajah Azure.

  2. Di Azure Explorer, klik kanan pada nama langganan lalu pilih Create Resource....

  3. Pilih Buat Aplikasi Web Statis dari daftar.

  4. Ikuti perintah menggunakan tabel berikut untuk memahami cara membuat sumber daya Static Web App Anda.

    Harta benda Nilai
    Masukkan nama unik global untuk aplikasi web baru. Masukkan nilai unik seperti fileuploadstor, untuk nama sumber daya Penyimpanan Anda.

    Nama unik ini adalah nama sumber daya Anda yang digunakan di bagian berikutnya. Gunakan hanya karakter dan angka, hingga 24 panjangnya. Anda memerlukan nama akun ini untuk digunakan nanti.
    Pilih lokasi untuk sumber daya baru. Gunakan lokasi yang direkomendasikan.

  5. Ikuti perintah untuk memberikan informasi berikut:

    Cepat Masuk
    Pilih grup sumber daya untuk sumber daya baru. Gunakan grup sumber daya yang Anda buat untuk sumber daya penyimpanan Anda.
    Masukkan nama untuk aplikasi web statis baru. Terima nama default.
    Pilih SKU Pilih SKU gratis untuk tutorial ini. Jika Anda sudah memiliki sumber daya Static Web App gratis di langganan Anda, pilih tingkat harga berikutnya.
    Pilih preset build untuk mengonfigurasi struktur proyek default. Pilih Kustom.
    Pilih lokasi kode aplikasi Anda azure-upload-file-to-storage/app
    Pilih lokasi kode Azure Functions Anda azure-upload-file-to-storage/api
    Masukkan jalur output build Anda... dist

    nilai adalah jalur dari aplikasi Anda ke file statis (dihasilkan).
    Pilih lokasi untuk sumber daya baru. Pilih wilayah yang dekat dengan Anda.

  6. Setelah proses selesai, pop-up pemberitahuan akan ditampilkan. Pilih Tampilkan/Edit Alur Kerja.

  7. Fork jarak jauh Anda memiliki file alur kerja baru untuk penerapan ke Static Web Apps. Tarik file tersebut ke lingkungan Anda dengan perintah berikut di terminal:

    git pull origin main

  8. Buka file alur kerja yang terletak di /.github/workflows/.

  9. Periksa bagian alur kerja khusus untuk aplikasi Web Statis tutorial ini seharusnya terlihat seperti:

    ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
app_location: "/azure-upload-file-to-storage/app" # App source code path
api_location: "/azure-upload-file-to-storage/api" # Api source code path - optional
output_location: "dist" # Built app content directory - optional
###### End of Repository/Build Configurations ######

  10. Pergi ke fork GitHub Anda untuk sampel, https://github.com/<YOUR-ACCOUNT>/azure-typescript-e2e-apps/actions, untuk memverifikasi apakah aksi build dan deploy, yang bernama Azure Static Web Apps CI/CD, berhasil diselesaikan. Tindakan ini mungkin perlu waktu beberapa menit untuk diselesaikan.

  11. Buka portal Microsoft Azure untuk aplikasi Anda dan lihat bagian API dari Pengaturan . Nama Sumber Daya Backend di lingkungan produksi (managed) menunjukkan API Anda berhasil disebarkan.

  12. Pilih (terkelola) untuk melihat daftar API yang dimuat di aplikasi:

    • daftar
    • Sas
    • keadaan

  13. Buka halaman Gambaran Umum untuk menemukan URL untuk aplikasi yang Anda sebarkan.

  14. Penyebaran aplikasi selesai.

Mengonfigurasi API dengan nama dan kunci sumber daya Storage

Aplikasi ini memerlukan nama dan kunci sumber daya Azure Storage sebelum API berfungsi dengan benar. Saat disebarkan ke Azure Static Web Apps, aplikasi klien dan API dihosting dari domain yang sama, menghilangkan kebutuhan untuk mengatur variabel lingkungan aplikasi klien VITE_API_SERVER.

  1. Masih di Azure Explorer, klik kanan pada sumber daya Static Web App dan pilih Buka di Portal.

  2. Pilih Konfigurasi di bagian Pengaturan.

  3. Tambahkan pengaturan aplikasi menggunakan tabel berikut.

    Harta benda Nilai Deskripsi
    Nama_Akun_Azure_Storage Nama akun Azure Storage, misalnya: fileuploadstor. Digunakan dalam kode sumber untuk menyambungkan ke sumber daya Storage.
    Azure_Storage_AccountKey Kunci akun Azure Storage Digunakan dalam kode sumber untuk menyambungkan ke sumber daya Storage.

  4. Pilih Simpan pada halaman Konfigurasi untuk menyimpan kedua pengaturan.

Menggunakan aplikasi web statis yang disebarkan Azure

Verifikasi penyebaran dan konfigurasi berhasil dengan menggunakan situs web.

  1. Di Visual Studio Code, klik kanan aplikasi web Statis Anda dari penjelajah Azure dan pilih Telusuri situs.
  2. Di jendela browser web baru, pilih Pilih File lalu pilih file gambar (*.png atau *.jpg) untuk diunggah.
  3. Pilih Dapatkan token sas. Tindakan ini meneruskan nama file ke API dan menerima URL token SAS yang diperlukan untuk mengunggah file.
  4. Pilih Unggah file untuk menggunakan URL token SAS untuk mengunggah file. Browser menampilkan gambar mini dan URL file yang diunggah.

Membersihkan sumber daya

Di Visual Studio Code, gunakan penjelajah Azure untuk Grup Sumber Daya. Klik kanan pada grup sumber daya Anda lalu pilih Hapus.

Tindakan ini menghapus semua sumber daya dalam grup, termasuk sumber daya aplikasi Storage dan Static Web Anda.

Pemecahan masalah

Laporkan masalah dengan sampel ini di repositori GitHub. Sertakan hal-hal berikut dengan masalah:

  • URL dari artikel
  • Langkah atau konteks dalam artikel yang bermasalah
  • Lingkungan pengembangan Anda

Contoh kode

Konten terkait