Mengunggah gambar ke blob Azure Storage dengan JavaScript

  • Artikel

Gunakan aplikasi web statis untuk mengunggah file ke blob Azure Storage menggunakan paket npm Azure Storage @azure/storage-blob dengan token SAS Azure Storage.

Prasyarat

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

Arsitektur aplikasi

Arsitektur aplikasi ini mencakup dua sumber daya Azure:

  • Azure Static Web Apps untuk aplikasi klien yang dihasilkan secara statis. Sumber daya juga menyediakan API Azure Functions terkelola. Dikelola berarti bahwa sumber daya Static Web Apps mengelola sumber daya API untuk penggunaannya sendiri.
  • Azure Storage untuk penyimpanan blob.

Diagram showing how a customer interacts from their computer to use the website to upload a file to Azure Storage directly.

Langkah Deskripsi
1 Pelanggan terhubung ke situs web yang dihasilkan secara statis. Situs web dihosting di Azure Static Web Apps.
2 Pelanggan menggunakan situs web tersebut, untuk memilih file yang akan diunggah. Untuk tutorial ini, kerangka kerja front-end adalah Vite React dan file yang diunggah adalah file gambar.
3 Situs web memanggil API sas Azure Functions untuk mendapatkan token SAS berdasarkan nama file file yang tepat 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 build

Tutorial ini menggunakan lingkungan berikut:

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

1. Repositori aplikasi sampel Fork 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 membuat fork sampel dengan cabang utama saja.

2. Mengonfigurasi lingkungan dev

Lingkungan kontainer pengembangan tersedia dengan semua 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 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 di main cabang fork Anda dengan memilih tombol CODE .

    GitHub screenshot of Code Spaces buttons for a repository.

  2. Pada tab Codespace, pilih elipsis, ....

    GitHub screenshot of Code Spaces tab with ellipsis control highlighted.

  3. Pilih + Baru dengan opsi untuk memilih kontainer dev Codespaces tertentu.

    GitHub screenshot of Codespaces New with options menu item highlighted.

  4. Pilih opsi berikut lalu pilih Buat ruang kode.

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

    GitHub screenshot of Codespaces New with options menu with the following dev container highlighted, Tutorial: Upload file to storage with SAS Token.

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

  6. Buka terminal baru di codespace.

    Tip

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

    Screenshot of the codespaces menu option to open a new terminal.

  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.

3. Memasang dependensi

Aplikasi sampel untuk tutorial ini ada di azure-upload-file-to-storage folder . 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

4. Buat sumber daya Storage dengan ekstensi Visual Studio

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

  • Pemicu di aplikasi Azure Functions
  • Penyimpanan blob (file)

  1. Navigasikan ke ekstensi Azure Storage.

  2. Masuk ke Azure jika perlu.

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

    Screenshot of Visual Studio Code in the Azure Explorer with the right-click menu showing the Create Resource item highlighted.

  4. Pilih Buat Akun Penyimpanan dari daftar.

  5. Ikuti petunjuk menggunakan tabel berikut untuk memahami cara membuat sumber daya Penyimpanan Anda.

    Properti Nilai
    Masukkan nama yang unik secara global untuk aplikasi web yang 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.

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

    Screenshot of Visual Studio Code showing the Azure Activity Bar and the notification that the storage account was successfully created.

5. Mengonfigurasi CORS Penyimpanan

Karena browser digunakan untuk mengunggah file, akun Azure Storage perlu mengonfigurasi CORS untuk mengizinkan permintaan lintas asal.

  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 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

    Pengaturan 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.

  4. Pilih Simpan.

6. Memberikan akses anonim ke penyimpanan

Unggahan file diamankan dari klien saat Anda membuat token SAS terbatas waktu dan terbatas izin. Namun, setelah file diunggah, dalam skenario tutorial ini, Anda ingin siapa pun melihatnya. Untuk melakukannya, Anda perlu mengubah izin penyimpanan agar dapat diakses secara publik.

Meskipun akun dapat diakses secara publik, setiap kontainer dan setiap blob dapat memiliki akses privat. Metode yang lebih aman tetapi terlalu rumit untuk tutorial ini adalah mengunggah ke satu akun penyimpanan dengan token SAS, lalu memindahkan blob ke akun penyimpanan lain dengan akses publik.

  1. Untuk mengaktifkan akses publik di portal 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.

7. Buat kontainer unggahan

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

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

    • Nama: upload
    • Tingkat akses publik: Blob

  3. Pilih Buat.

8. Beri diri Anda akses Data Blob

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

  1. Masih di akun penyimpanan portal Azure, pilih Kontrol Akses (IAM).
  2. Pilih Tambahkan penetapan peran.
  3. Cari dan pilih Kontributor Data Blob Penyimpanan. Pilih Selanjutnya.
  4. Pilih + Pilih anggota.
  5. Cari dan pilih akun Anda.
  6. Pilih Tinjau + tetapkan.
  7. Pilih Kontainer lalu kontainer unggah . Anda seharusnya dapat melihat tidak ada blob dalam kontainer tanpa kesalahan otorisasi.

9. Dapatkan 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 Azure, di bagian Keamanan + jaringan, pilih Kunci akses.

  2. Ingat file API ditemukan di ./workspaces/azure-typescript-e2e-apps/azure-upload-file-to-storage/api.

  3. Di folder API, ganti nama file dari local.settings.json.sample menjadi local.settings.json. File diabaikan oleh Git sehingga tidak akan diperiksa ke kontrol sumber.

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

    Properti Nilai Deskripsi
    Azure_Storage_AccountName 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 akun Azure Storage string koneksi Gunakan 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 hanya perlu mengatur nilai Azure_Storage_AccountName dan Azure_Storage_AccountKey yang digunakan dalam kode sumber.

10. Jalankan 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 lalu 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 ke aplikasi fungsi.

  5. Tambahkan rute API ke bilah alamat URL: /api/sas?container=upload&file=test.png. Tidak apa-apa bahwa file belum ada dalam kontainer. 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 segalanya sebelum /api/sas.

11. Mengonfigurasi dan menjalankan aplikasi klien

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

  2. .env Buka file 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 bola dunia.

  6. Anda akan melihat aplikasi web sederhana.

    Screenshot of web browser showing web app with Select File button available.

  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.

    Screenshot of web browser showing web app with the image file uploaded and a thumbnail of the file displayed.

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

12. 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 app folder dan api untuk tutorial ini.

13. Menyebarkan aplikasi web statis ke Azure

Aplikasi Azure Functions menggunakan fitur pratinjau, aplikasi harus disebarkan ke US Barat 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.

    Properti Nilai
    Masukkan nama yang unik secara global untuk aplikasi web yang 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 permintaan untuk memberikan informasi berikut:

    Prompt Enter
    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 statik 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
    Memilih lokasi kode Azure Functions Anda azure-upload-file-to-storage/api
    Masukkan jalur output build Anda... dist

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

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

  7. Fork jarak jauh Anda memiliki file alur kerja baru untuk disebarkan 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. Verifikasi dia bagian dari alur kerja khusus untuk aplikasi Web Statis tutorial ini akan 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. Buka fork GitHub sampel Anda, https://github.com/YOUR-ACCOUNT/azure-typescript-e2e-apps/actions untuk memverifikasi tindakan build dan deploy, bernama Azure Static Web Apps CI/CD, berhasil diselesaikan. Mungkin diperlukan waktu beberapa menit hingga selesai.

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

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

    • list
    • Sas
    • status

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

  14. Penyebaran aplikasi selesai.

14. Mengonfigurasi API dengan nama dan kunci sumber daya Penyimpanan

Aplikasi ini memerlukan nama dan kunci sumber daya Azure Storage sebelum API berfungsi dengan benar.

  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.

    Properti Nilai Deskripsi
    Azure_Storage_AccountName 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 di halaman Konfigurasi untuk menyimpan kedua pengaturan.

Catatan

Anda tidak perlu mengatur variabel env aplikasi klien VITE_API_SERVER karena aplikasi klien dan API dihosting dari domain yang sama.

15. Gunakan 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.

16. Bersihkan sumber daya

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

Ini menghapus semua sumber daya dalam grup, termasuk sumber daya Aplikasi web Penyimpanan dan Statis Anda.

Pemecahan Masalah

Laporkan masalah dengan sampel ini di repositori GitHub yang disebutkan di bawah ini. Sertakan yang berikut ini dengan masalah:

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

Kode Sampel

Konten terkait

Jika Anda ingin melanjutkan aplikasi ini, pelajari cara menyebarkan aplikasi ke Azure untuk hosting dengan salah satu pilihan berikut: