Mulai cepat: Mengirim peristiwa ke atau menerima peristiwa dari hub peristiwa dengan menggunakan JavaScript

Dalam Mulai Cepat ini, Anda mempelajari cara mengirim peristiwa ke dan menerima peristiwa dari hub peristiwa menggunakan paket npm @azure/event-hubs .

Prasyarat

Jika Anda baru menggunakan Azure Event Hubs, lihat Ringkasan Event Hubs sebelum Anda melakukan mulai cepat ini.

Untuk menyelesaikan mulai cepat ini, Anda memerlukan prasyarat berikut:

  • Langganan Microsoft Azure. Untuk menggunakan layanan Azure, termasuk Azure Event Hubs, Anda memerlukan langganan. Jika Anda tidak memiliki akun Azure yang sudah ada, Anda dapat mendaftar untuk coba gratis.
  • Node.js LTS. Unduh versi dukungan jangka panjang (LTS) terbaru.
  • Visual Studio Code (disarankan) atau lingkungan pengembangan terpadu (IDE) lainnya.
  • Membuat ruang nama Azure Event Hubs dan pusat aktivitas. Langkah pertama yaitu gunakan portal Microsoft Azure untuk membuat kumpulan nama Event Hubs jenis, dan dapatkan info masuk manajemen yang diperlukan aplikasi Anda untuk berkomunikasi dengan pusat aktivitas. Untuk membuat namespace layanan dan pusat aktivitas, ikuti prosedur dalam artikel ini.

Menginstal paket npm untuk mengirim peristiwa

Untuk menginstal paket Node Package Manager (npm) untuk Event Hubs, buka prompt perintah yang memiliki npm di jalurnya, ubah direktori ke folder tempat Anda ingin menyimpan sampel Anda.

Jalankan perintah ini:

npm install @azure/event-hubs
npm install @azure/identity

Mengautentikasi aplikasi ke Azure

Mulai cepat ini menunjukkan kepada Anda dua cara menyambungkan ke Azure Event Hubs: tanpa kata sandi dan string koneksi. Opsi pertama menunjukkan cara menggunakan prinsip keamanan Anda di ID Microsoft Entra dan kontrol akses berbasis peran (RBAC) untuk menyambungkan ke namespace Layanan Pusat Aktivitas. Anda tidak perlu khawatir tentang memiliki string koneksi yang dikodekan secara permanen dalam kode Anda atau dalam file konfigurasi atau dalam penyimpanan aman seperti Azure Key Vault. Opsi kedua menunjukkan cara menggunakan string koneksi untuk menyambungkan ke namespace Layanan Pusat Aktivitas. Jika Anda baru menggunakan Azure, Anda mungkin menemukan opsi string koneksi lebih mudah diikuti. Sebaiknya gunakan opsi tanpa kata sandi di aplikasi dunia nyata dan lingkungan produksi. Untuk informasi selengkapnya, lihat Autentikasi dan otorisasi. Anda juga dapat membaca selengkapnya tentang autentikasi tanpa kata sandi di halaman gambaran umum.

Menetapkan peran ke pengguna Microsoft Entra Anda

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang tersambung ke Azure Event Hubs memiliki izin yang benar. Anda memerlukan peran Pemilik Data Azure Event Hubs untuk mengirim dan menerima pesan. Untuk menetapkan sendiri peran ini, Anda memerlukan peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan.Microsoft.Authorization/roleAssignments/write Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Pelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan .

Contoh berikut menetapkan peran ke Azure Event Hubs Data Owner akun pengguna Anda, yang menyediakan akses penuh ke sumber daya Azure Event Hubs. Dalam skenario nyata, ikuti Prinsip Hak Istimewa Paling Sedikit untuk memberi pengguna hanya izin minimum yang diperlukan untuk lingkungan produksi yang lebih aman.

Peran bawaan Azure untuk Azure Event Hubs

Untuk Azure Event Hubs, pengelolaan namespace layanan dan semua sumber daya terkait melalui portal Azure dan API manajemen sumber daya Azure sudah dilindungi menggunakan model Azure RBAC. Azure menyediakan peran bawaan Azure di bawah ini untuk mengotorisasi akses ke namespace Layanan Pusat Aktivitas:

  • Pemilik Data Azure Event Hubs: Memungkinkan akses data ke namespace Layanan Pusat Aktivitas dan entitasnya (antrean, topik, langganan, dan filter)
  • Pengirim Data Azure Event Hubs: Gunakan peran ini untuk memberi pengirim akses ke namespace layanan Azure Event Hubs dan entitasnya.
  • Penerima Data Azure Event Hubs: Gunakan peran ini untuk memberi penerima akses ke namespace Layanan Azure Event Hubs dan entitasnya.

Jika Anda ingin membuat peran kustom, lihat Hak yang diperlukan untuk operasi Azure Event Hubs.

Penting

Dalam kebanyakan kasus, akan memakan waktu satu atau dua menit agar penetapan peran disebarluaskan di Azure. Dalam kasus yang jarang terjadi, mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan namespace Layanan Pusat Aktivitas Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Pada halaman gambaran umum, pilih Kontrol akses (IAM) dari menu sebelah kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

    Cuplikan layar yang menampilkan cara menetapkan peran.

  5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Azure Event Hubs Data Owner dan pilih hasil yang cocok. Kemudian pilih Berikutnya.

  6. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  8. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Mengirim aktivitas

Di bagian ini, Anda membuat aplikasi JavaScript yang mengirim peristiwa ke pusat aktivitas.

  1. Buka editor favorit Anda, seperti Visual Studio Code.

  2. Buat file dengan nama send.js, dan tempelkan kode di bawah ini ke dalamnya:

    Dalam kode, gunakan nilai nyata untuk mengganti tempat penampung berikut:

    • EVENT HUBS NAMESPACE NAME
    • EVENT HUB NAME
    const { EventHubProducerClient } = require("@azure/event-hubs");
    const { DefaultAzureCredential } = require("@azure/identity");
    
    // Event hubs 
    const eventHubsResourceName = "EVENT HUBS NAMESPACE NAME";
    const fullyQualifiedNamespace = `${eventHubsResourceName}.servicebus.windows.net`; 
    const eventHubName = "EVENT HUB NAME";
    
    // Azure Identity - passwordless authentication
    const credential = new DefaultAzureCredential();
    
    async function main() {
    
      // Create a producer client to send messages to the event hub.
      const producer = new EventHubProducerClient(fullyQualifiedNamespace, eventHubName, credential);
    
      // Prepare a batch of three events.
      const batch = await producer.createBatch();
      batch.tryAdd({ body: "passwordless First event" });
      batch.tryAdd({ body: "passwordless Second event" });
      batch.tryAdd({ body: "passwordless Third event" });    
    
      // Send the batch to the event hub.
      await producer.sendBatch(batch);
    
      // Close the producer client.
      await producer.close();
    
      console.log("A batch of three events have been sent to the event hub");
    }
    
    main().catch((err) => {
      console.log("Error occurred: ", err);
    });
    
  3. Jalankan node send.js untuk menjalankan file ini. Perintah ini mengirimkan batch tiga peristiwa ke pusat aktivitas. Jika Anda menggunakan autentikasi Tanpa Kata Sandi (Kontrol Akses Berbasis Peran Azure Active Directory), Anda mungkin ingin menjalankan az login dan masuk ke Azure menggunakan akun yang ditambahkan ke peran Pemilik Data Azure Event Hubs.

  4. Di portal Azure, verifikasi bahwa pusat aktivitas menerima pesan. Refresh halaman untuk memperbarui bagan. Mungkin perlu beberapa detik agar pesan diterima.

    Verifikasi bahwa event hub menerima pesan

    Catatan

    Untuk kode sumber lengkap, termasuk komentar informasi tambahan, buka halaman sendEvents.js GitHub.

Menerima peristiwa

Di bagian ini, Anda menerima peristiwa dari pusat aktivitas dengan menggunakan kumpulan titik pemeriksaan penyimpanan Azure Blob di aplikasi JavaScript. Program menjalankan titik pemeriksaan metadata pada pesan yang diterima dalam interval rutin dalam blob Azure Storage. Pendekatan ini memudahkan untuk terus menerima pesan nanti dari posisi terakhir Anda.

Ikuti rekomendasi ini saat menggunakan Azure Blob Storage sebagai penyimpanan titik pemeriksaan:

  • Gunakan kontainer terpisah untuk setiap grup konsumen. Anda dapat menggunakan akun penyimpanan yang sama, tetapi menggunakan satu kontainer per setiap grup.
  • Jangan gunakan kontainer untuk hal lain, dan jangan gunakan akun penyimpanan untuk hal lain.
  • Akun penyimpanan harus berada di wilayah yang sama dengan aplikasi yang disebarkan berada. Jika aplikasi lokal, coba pilih wilayah terdekat yang mungkin.

Pada halaman Akun penyimpanan di portal Azure, di bagian Blob service, pastikan bahwa pengaturan berikut dinonaktifkan.

  • Namespace hierarkis
  • Penghapusan sementara blob
  • Penerapan versi

Membuat akun Azure Storage dan kontainer blob

Untuk membuat akun penyimpanan Azure dan kontainer blob di dalamnya, lakukan tindakan berikut:

  1. Membuat akun Azure Storage
  2. Membuat kontainer blob di akun penyimpanan
  3. Mengautentikasi ke kontainer blob

Saat mengembangkan secara lokal, pastikan bahwa akun pengguna yang mengakses data blob memiliki izin yang benar. Anda akan memerlukan Kontributor Data Blob Penyimpanan untuk membaca dan menulis data blob. Untuk menetapkan sendiri peran ini, Anda harus diberi peran Administrator Akses Pengguna, atau peran lain yang menyertakan tindakan Microsoft.Authorization/roleAssignments/write . Anda dapat menetapkan peran Azure RBAC kepada pengguna menggunakan portal Azure, Azure CLI, atau Azure PowerShell. Anda dapat mempelajari selengkapnya tentang cakupan yang tersedia untuk penetapan peran di halaman gambaran umum cakupan.

Dalam skenario ini, Anda akan menetapkan izin ke akun pengguna, yang tercakup ke akun penyimpanan, untuk mengikuti Prinsip Hak Istimewa Paling Rendah. Praktik ini hanya memberi pengguna izin minimum yang diperlukan dan menciptakan lingkungan produksi yang lebih aman.

Contoh berikut akan menetapkan peran Kontributor Data Blob Penyimpanan ke akun pengguna Anda, yang menyediakan akses baca dan tulis ke data blob di akun penyimpanan Anda.

Penting

Dalam kebanyakan kasus, dibutuhkan satu atau dua menit agar penetapan peran disebarluaskan di Azure, tetapi dalam kasus yang jarang terjadi mungkin perlu waktu hingga delapan menit. Jika Anda menerima kesalahan autentikasi saat pertama kali menjalankan kode, tunggu beberapa saat dan coba lagi.

  1. Di portal Azure, temukan akun penyimpanan Anda menggunakan bilah pencarian utama atau navigasi kiri.

  2. Di halaman gambaran umum akun penyimpanan, pilih Kontrol akses (IAM) dari menu kiri.

  3. Di halaman Kontrol akses (IAM), pilih tab Penetapan peran.

  4. Pilih + Tambahkan dari menu atas lalu Tambahkan penetapan peran dari menu drop-down yang dihasilkan.

    Cuplikan layar yang menunjukkan cara menetapkan peran akun penyimpanan.

  5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Kontributor Data Blob Penyimpanan dan pilih hasil yang cocok, lalu pilih Berikutnya.

  6. Di bagian Tetapkan akses ke, pilih Pengguna, grup, atau perwakilan layanan, lalu pilih + Pilih anggota.

  7. Dalam dialog, cari nama pengguna Microsoft Entra Anda (biasanya alamat email user@domain Anda) lalu pilih Pilih di bagian bawah dialog.

  8. Pilih Tinjau + tetapkan untuk masuk ke halaman akhir, lalu Tinjau + tetapkan lagi untuk menyelesaikan proses.

Menginstal paket npm untuk menerima peristiwa

Untuk sisi penerimaan, Anda perlu menginstal dua paket lagi. Dalam mulai cepat ini, Anda menggunakan penyimpanan Azure Blob untuk mempertahankan titik pemeriksaan sehingga program tidak membaca peristiwa yang sudah dibacanya. Program menjalankan titik pemeriksaan metadata pada pesan yang diterima dalam interval rutin dalam blob. Pendekatan ini memudahkan untuk terus menerima pesan nanti dari posisi terakhir Anda.

Jalankan perintah ini:

npm install @azure/storage-blob
npm install @azure/eventhubs-checkpointstore-blob
npm install @azure/identity

Menulis kode untuk menerima peristiwa

  1. Buka editor favorit Anda, seperti Visual Studio Code.

  2. Buat file bernama send.js, dan tempelkan kode berikut ini ke dalamnya:

    Dalam kode, gunakan nilai nyata untuk mengganti tempat penampung berikut:

    • EVENT HUBS NAMESPACE NAME
    • EVENT HUB NAME
    • STORAGE ACCOUNT NAME
    • STORAGE CONTAINER NAME
    const { DefaultAzureCredential } = require("@azure/identity");
    const { EventHubConsumerClient, earliestEventPosition  } = require("@azure/event-hubs");
    const { ContainerClient } = require("@azure/storage-blob");    
    const { BlobCheckpointStore } = require("@azure/eventhubs-checkpointstore-blob");
    
    // Event hubs 
    const eventHubsResourceName = "EVENT HUBS NAMESPACE NAME";
    const fullyQualifiedNamespace = `${eventHubsResourceName}.servicebus.windows.net`; 
    const eventHubName = "EVENT HUB NAME";
    const consumerGroup = "$Default"; // name of the default consumer group
    
    // Azure Storage 
    const storageAccountName = "STORAGE ACCOUNT NAME";
    const storageContainerName = "STORAGE CONTAINER NAME";
    const baseUrl = `https://${storageAccountName}.blob.core.windows.net`;
    
    // Azure Identity - passwordless authentication
    const credential = new DefaultAzureCredential();
    
    async function main() {
    
      // Create a blob container client and a blob checkpoint store using the client.
      const containerClient = new ContainerClient(
        `${baseUrl}/${storageContainerName}`,
        credential
      );  
      const checkpointStore = new BlobCheckpointStore(containerClient);
    
      // Create a consumer client for the event hub by specifying the checkpoint store.
      const consumerClient = new EventHubConsumerClient(consumerGroup, fullyQualifiedNamespace, eventHubName, credential, checkpointStore);
    
      // Subscribe to the events, and specify handlers for processing the events and errors.
      const subscription = consumerClient.subscribe({
          processEvents: async (events, context) => {
            if (events.length === 0) {
              console.log(`No events received within wait time. Waiting for next interval`);
              return;
            }
    
            for (const event of events) {
              console.log(`Received event: '${event.body}' from partition: '${context.partitionId}' and consumer group: '${context.consumerGroup}'`);
            }
            // Update the checkpoint.
            await context.updateCheckpoint(events[events.length - 1]);
          },
    
          processError: async (err, context) => {
            console.log(`Error : ${err}`);
          }
        },
        { startPosition: earliestEventPosition }
      );
    
      // After 30 seconds, stop processing.
      await new Promise((resolve) => {
        setTimeout(async () => {
          await subscription.close();
          await consumerClient.close();
          resolve();
        }, 30000);
      });
    }
    
    main().catch((err) => {
      console.log("Error occurred: ", err);
    });
    
  3. Jalankan node receive.js dalam prompt perintah untuk menjalankan file ini. Jendela akan menampilkan pesan tentang peristiwa yang diterima.

    C:\Self Study\Event Hubs\JavaScript>node receive.js
    Received event: 'First event' from partition: '0' and consumer group: '$Default'
    Received event: 'Second event' from partition: '0' and consumer group: '$Default'
    Received event: 'Third event' from partition: '0' and consumer group: '$Default'
    

    Catatan

    Untuk kode sumber lengkap, termasuk komentar informasi tambahan, buka halaman receiveEventsUsingCheckpointStore.js GitHub.

    Program penerima menerima peristiwa dari semua partisi grup konsumen default di pusat aktivitas.

Membersihkan sumber daya

Hapus grup sumber daya yang memiliki namespace Layanan Pusat Aktivitas atau hapus hanya namespace jika Anda ingin menyimpan grup sumber daya.

Periksa sampel di GitHub: