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

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

Jika Anda baru menggunakan Azure Event Hubs, lihat Gambaran umum Azure Event Hubs sebelum memulai.

Prasyarat

• Langganan Microsoft Azure. Untuk menggunakan layanan Azure, termasuk Azure Event Hubs, Anda memerlukan langganan. Jika Anda tidak memiliki akun Azure, daftar untuk uji 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. Gunakan portal Microsoft Azure untuk membuat namespace jenis Azure Event Hubs Dapatkan kredensial manajemen yang perlu dikomunikasikan aplikasi Anda dengan pusat aktivitas. Untuk informasi selengkapnya, lihat Membuat pusat aktivitas menggunakan portal Microsoft Azure.

Menginstal paket npm untuk mengirim peristiwa

Untuk menginstal paket Node Package Manager (npm) untuk Event Hubs, buka jendela Prompt Perintah yang sudah menyertakan npm dalam jalurnya. Ubah direktori ke folder tempat Anda ingin menyimpan sampel Anda.

Tanpa Kata Sandi (Disarankan)

Jalankan perintah ini:

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

String Koneksi

Jalankan perintah ini:

npm install @azure/event-hubs

Mengautentikasi aplikasi ke Azure

Panduan cepat ini menunjukkan kepada Anda dua cara menghubungkan ke Azure Event Hubs:

• Tanpa kata sandi. Gunakan prinsip keamanan Anda di ID Microsoft Entra dan kontrol akses berbasis peran (RBAC) untuk menyambungkan ke namespace Layanan Pusat Aktivitas. Anda tidak perlu khawatir memiliki string koneksi yang dikodekan secara permanen dalam kode Anda, dalam file konfigurasi, atau di penyimpanan aman seperti Azure Key Vault.
• String koneksi. Gunakan 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 Bus Layanan dan koneksi Tanpa Kata Sandi untuk layanan Azure.

Tanpa Kata Sandi (Disarankan)

Menetapkan peran ke pengguna Microsoft Entra Anda

Saat Anda mengembangkan secara lokal, pastikan 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. Untuk informasi selengkapnya, lihat Memahami cakupan untuk halaman Azure RBAC .

Contoh berikut mengaitkan peran Azure Event Hubs Data Owner dengan akun pengguna Anda, yang memberikan 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 berikut untuk mengotorisasi akses ke namespace Layanan Pusat Aktivitas:

• Pemilik Data Azure Event Hubs: Memungkinkan akses data ke namespace layanan Azure Event Hubs dan entitasnya (antrean, topik, langganan, dan filter).
• Pengirim Data Azure Event Hubs: Gunakan peran ini untuk memberi pengirim akses ke namespace Event Hubs dan entitasnya.
• Azure Event Hubs Data Receiver: Gunakan peran ini untuk memberi penerima akses ke namespace Event Hubs dan entitas-entalitasnya.

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

Penting

Dalam kebanyakan kasus, dibutuhkan 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.

Portal Microsoft Azure

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 pilih Tambahkan penetapan 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 bawah 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). Pilih Pilih di bagian bawah dialog.

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

Azure CLI

Untuk menetapkan peran di tingkat sumber daya menggunakan Azure CLI, pertama-tama dapatkan ID sumber daya menggunakan az eventhubs namespace show perintah . Anda dapat memfilter properti output menggunakan parameter --query.

az eventhubs namespace show -g '<your-event-hub-resource-group>' -n '<your-event-hub-name>' --query id

Salin output Id dari perintah sebelumnya. Anda kemudian dapat menetapkan peran menggunakan perintah peran az .

az role assignment create --assignee "<user@domain>" \
--role "Azure Event Hubs Data Owner" \
--scope "<your-resource-id>"

PowerShell

Untuk menetapkan peran di tingkat sumber daya menggunakan Azure PowerShell, pertama-tama dapatkan ID sumber daya menggunakan Get-AzResource perintah .

Get-AzResource -ResourceGroupName "<your-event-hub-resource-group>" -Name "<your-event-hub-name>"

Salin nilai Id dari output perintah sebelumnya. Anda kemudian dapat menetapkan peran menggunakan perintah New-AzRoleAssignment .

New-AzRoleAssignment -SignInName <user@domain> `
-RoleDefinitionName "Azure Event Hubs Data Owner" `
-Scope <yourResourceId>

String Koneksi

Dapatkan string koneksi

Membuat namespace baru secara otomatis menghasilkan kebijakan Tanda Tangan Akses Bersama (SAS) awal dengan kunci primer dan sekunder dan string koneksi yang masing-masing memberikan kontrol penuh atas semua aspek namespace layanan. Untuk informasi tentang cara membuat aturan dengan hak yang lebih dibatasi untuk pengirim dan penerima reguler, lihat Autentikasi dan otorisasi Azure Event Hubs.

Klien dapat menggunakan string koneksi untuk menyambungkan ke namespace Layanan Pusat Aktivitas. Untuk menyalin string koneksi utama namespace layanan Anda, ikuti langkah-langkah berikut:

1. Pada halaman Event Hub Namespace, pilih Kebijakan Akses Bersama di menu sebelah kiri.

2. Pada halaman Kebijakan akses bersama, pilih RootManageSharedAccessKey.

3. Di jendela Kebijakan: RootManageSharedAccessKey, pilih tombol salin di samping String Koneksi Utama, untuk menyalin string koneksi ke clipboard Anda untuk digunakan nanti. Tempelkan nilai ini ke Notepad atau beberapa lokasi sementara lainnya.

   

   Anda dapat menggunakan halaman ini untuk menyalin kunci primer, kunci sekunder, dan string koneksi sekunder.

Kirim acara

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

1. Buka editor teks, seperti Visual Studio Code.

2. Buat file yang disebut send.js. Tempelkan kode berikut ke dalamnya:

   Tanpa Kata Sandi (Disarankan)

   Dalam kode, gunakan nilai nyata untuk mengganti placeholder 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);
   });
   

   String Koneksi

   Dalam kode, gunakan nilai nyata untuk mengganti placeholder berikut:

   • EVENT HUB NAME
   • EVENT HUBS NAMESPACE CONNECTION STRING

   const { EventHubProducerClient } = require("@azure/event-hubs");
   
   const connectionString = "EVENT HUBS NAMESPACE CONNECTION STRING";
   const eventHubName = "EVENT HUB NAME";
   
   async function main() {
   
     // Create a producer client to send messages to the event hub.
     const producer = new EventHubProducerClient(connectionString, eventHubName);
   
     // Prepare a batch of three events.
     const batch = await producer.createBatch();
     batch.tryAdd({ body: "First event" });
     batch.tryAdd({ body: "Second event" });
     batch.tryAdd({ body: "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. Untuk menjalankan aplikasi, gunakan perintah ini:

   node send.js
   

   Perintah mengirimkan batch tiga peristiwa ke pusat aktivitas Anda.

   Jika Anda menggunakan autentikasi tanpa kata sandi (Kontrol akses berbasis peran (RBAC) Microsoft Entra ID), Anda mungkin perlu masuk ke Azure menggunakan akun yang Anda tambahkan ke peran Pemilik Data Azure Event Hubs. Gunakan perintah az login.

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

   

   Nota

   Untuk informasi selengkapnya dan kode sumber lengkap, lihat halaman gitHub sendEvents.js.

Menerima peristiwa

Di bagian ini, Anda menerima peristiwa dari pusat acara dengan menggunakan penyimpanan titik pemeriksaan Azure Blob di aplikasi JavaScript. Ini melakukan titik pemeriksaan metadata pada pesan yang diterima secara berkala dalam blob Azure Storage. Pendekatan ini memudahkan untuk terus menerima pesan dari titik Anda berhenti.

Ikuti rekomendasi ini saat Anda 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 akun penyimpanan untuk hal lain.
• Jangan gunakan kontainer untuk hal lain.
• Buat akun penyimpanan di wilayah yang sama dengan aplikasi yang disebarkan. 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
• Pembuatan Versi

Membuat akun Azure Storage dan kontainer blob

Untuk membuat akun penyimpanan Azure dengan kontainer blob:

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

Tanpa Kata Sandi (Disarankan)

Saat Anda mengembangkan secara lokal, pastikan akun pengguna yang mengakses data blob memiliki izin yang benar. Anda memerlukan Kontributor Penyimpanan Data Blob untuk membaca dan menulis data blob. Untuk menetapkan peran ini pada diri Anda sendiri, Anda perlu 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. Untuk informasi selengkapnya, lihat Memahami cakupan untuk Azure RBAC.

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

Contoh berikut 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. 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.

Portal Microsoft Azure

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

2. Pada halaman akun penyimpanan, 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 pilih Tambahkan penetapan peran.

   

5. Gunakan kotak pencarian untuk memfilter hasil ke peran yang diinginkan. Untuk contoh ini, cari Pengelola Data Blob Penyimpanan. 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. Pilih Tinjau + tetapkan lagi untuk menyelesaikan proses.

Azure CLI

Untuk menetapkan peran di tingkat sumber daya menggunakan Azure CLI, pertama-tama dapatkan ID sumber daya menggunakan az storage account show perintah . Anda dapat memfilter properti output menggunakan parameter --query.

az storage account show --resource-group '<your-resource-group-name>' --name '<your-storage-account-name>' --query id

Salin output Id dari perintah sebelumnya. Anda kemudian dapat menetapkan peran menggunakan perintah peran az .

az role assignment create --assignee "<user@domain>" \
    --role "Storage Blob Data Contributor" \
    --scope "<your-resource-id>"

PowerShell

Untuk menetapkan peran di tingkat sumber daya menggunakan Azure PowerShell, pertama-tama dapatkan ID sumber daya menggunakan Get-AzResource perintah .

Get-AzResource -ResourceGroupName "<yourResourceGroupname>" -Name "<yourStorageAccountName>"

Salin nilai Id dari output perintah sebelumnya. Anda kemudian dapat menetapkan peran menggunakan perintah New-AzRoleAssignment .

New-AzRoleAssignment -SignInName <user@domain> `
    -RoleDefinitionName "Storage Blob Data Contributor" `
    -Scope <yourStorageAccountId>

String Koneksi

Dapatkan string koneksi ke akun penyimpanan. Lihat Mengonfigurasi string koneksi Azure Storage.

Perhatikan string koneksi dan nama kontainer. Anda menggunakannya dalam kode untuk menerima peristiwa.

Menginstal paket npm untuk menerima peristiwa

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

Tanpa Kata Sandi (Disarankan)

Jalankan perintah ini:

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

String Koneksi

Jalankan perintah ini:

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

Menulis kode untuk menerima peristiwa

1. Buka editor teks, seperti Visual Studio Code.

2. Buat file yang disebut receive.js. Tempelkan kode berikut ke dalamnya:

   Tanpa Kata Sandi (Disarankan)

   Dalam kode, gunakan nilai nyata untuk mengganti placeholder 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);
   });
   

   String Koneksi

   Dalam kode, gunakan nilai nyata untuk mengganti placeholder berikut:

   • EVENT HUBS NAMESPACE CONNECTION STRING
   • EVENT HUB NAME
   • STORAGE CONNECTION STRING
   • STORAGE CONTAINER NAME

   const { EventHubConsumerClient, earliestEventPosition  } = require("@azure/event-hubs");
   const { ContainerClient } = require("@azure/storage-blob");    
   const { BlobCheckpointStore } = require("@azure/eventhubs-checkpointstore-blob");
   
   const connectionString = "EVENT HUBS NAMESPACE CONNECTION STRING";    
   const eventHubName = "EVENT HUB NAME";
   const consumerGroup = "$Default"; // name of the default consumer group
   const storageConnectionString = "STORAGE CONNECTION STRING";
   const containerName = "STORAGE CONTAINER NAME";
   
   async function main() {
     // Create a blob container client and a blob checkpoint store using the client.
     const containerClient = new ContainerClient(storageConnectionString, containerName);
     const checkpointStore = new BlobCheckpointStore(containerClient);
   
     // Create a consumer client for the event hub by specifying the checkpoint store.
     const consumerClient = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName, 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. Untuk menjalankan kode ini, gunakan perintah node receive.js. Jendela 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'
   

   Nota

   Untuk kode sumber lengkap, termasuk komentar informasi, lihat receiveEventsUsingCheckpointStore.js.

   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.

Konten terkait

• Sampel JavaScript
• Sampel TypeScript