Aracılığıyla paylaş

JavaScript için Azure Event Grid istemci kitaplığı - sürüm 5.4.0

  • Makale

Azure Event Grid, büyük ölçekte güvenilir olay teslimi sağlayan bulut tabanlı bir hizmettir.

İstemci kitaplığını kullanarak:

  • Event Grid, Cloud Events 1.0 şemaları veya özel bir şema kullanarak Event Grid'e olay gönderme
  • Event Grid işleyicisine teslim edilen olayların kodunu çözme ve işleme
  • Event Grid konuları için Paylaşılan Erişim İmzaları Oluşturma

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

Daha fazla ayrıntı için destek ilkemize bakın.

Önkoşullar

Azure CLI kullanıyorsanız ve <your-resource-name> yerine kendi benzersiz adlarınızı yazın<your-resource-group-name>:

Event Grid Konusu Oluşturma

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Event Grid Etki Alanı Oluşturma

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

@azure/eventgrid paketini yükleyin

ile npmJavaScript için Azure Event Grid istemci kitaplığını yükleyin:

npm install @azure/eventgrid

Oluşturma ve kimlik doğrulaması EventGridPublisherClient

Event Grid API'sine erişmek üzere bir istemci nesnesi oluşturmak için Event Grid konunuzun ve öğesinin credentialolması gerekirendpoint. Event Grid istemcisi, erişim anahtarından oluşturulmuş bir Erişim Anahtarı veya Paylaşılan Erişim İmzası (SAS) kullanabilir.

Event Grid konunuzun uç noktasını Azure Portal'da veya aşağıdaki Azure CLI parçacığını kullanarak bulabilirsiniz:

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

Erişim Anahtarı Kullanma

Event Grid kaynağınıza göz atmak ve bir Erişim Anahtarı almak için Azure Portal'ı kullanın veya aşağıdaki Azure CLI parçacığını kullanın:

az eventgrid topic key list --resource-group <your-resource-group-name> --name <your-event-grid-topic-name>

API anahtarınız ve uç noktanız olduktan sonra, istemcinin kimliğini doğrulamak için sınıfını AzureKeyCredential aşağıdaki gibi kullanabilirsiniz:

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureKeyCredential("<Access Key>")
);

SAS Belirteci Kullanma

Erişim anahtarı gibi SAS belirteci de event Grid konusuna olay gönderme erişimine olanak tanır. Yeniden oluşturulana kadar kullanılabilecek erişim anahtarının aksine, SAS belirtecinin bir ifade süresi vardır ve bu süre artık geçerli değildir. Kimlik doğrulaması için SAS belirteci kullanmak için aşağıdakini AzureSASCredential kullanın:

const { EventGridPublisherClient, AzureSASCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new AzureSASCredential("<SAS Token>")
);

işlevini kullanarak generateSharedAccessSigniture sas belirteci oluşturabilirsiniz.

const { generateSharedAccessSignature, AzureKeyCredential } = require("@azure/eventgrid");

// Create a SAS Token which expires on 2020-01-01 at Midnight.
const token = generateSharedAccessSignature(
  "<endpoint>",
  new AzureKeyCredential("<API key>"),
  new Date("2020-01-01T00:00:00")
);

Azure Active Directory (AAD) kullanma

Azure EventGrid, isteklerin kimlik tabanlı kimlik doğrulaması için Azure Active Directory (Azure AD) ile tümleştirme sağlar. Azure AD ile kullanıcılara, gruplara veya uygulamalara Azure Event Grid kaynaklarınıza erişim vermek için rol tabanlı erişim denetimini (RBAC) kullanabilirsiniz.

Ile bir konuya veya etki alanına TokenCredentialolay göndermek için kimliği doğrulanmış kimliğin atanmış "EventGrid Veri Göndereni" rolüne sahip olması gerekir.

Paketle @azure/identity , hem geliştirme hem de üretim ortamlarında istekleri sorunsuz bir şekilde yetkilendirebilirsiniz. Azure Active Directory hakkında daha fazla bilgi edinmek için bkz @azure/identity . BENİOKU.

Örneğin, Azure Active Directory kullanarak kimlik doğrulaması yapacak bir istemci oluşturmak için kullanabilirsiniz DefaultAzureCredential :

const { EventGridPublisherClient } = require("@azure/eventgrid");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "<endpoint schema>",
  new DefaultAzureCredential()
);

Önemli kavramlar

EventGridPublisherClient

EventGridPublisherClient bir Event Grid Konusuna veya Event Grid Etki Alanına olay gönderirken kullanılır.

Olay Şemaları

Event Grid, olayları kodlamak için birden çok şemayı destekler. Özel Konu veya Etki Alanı oluşturulduğunda, olayları yayımlarken kullanılacak şemayı belirtirsiniz. Konunuzu özel bir şema kullanacak şekilde yapılandırabilirsiniz ancak önceden tanımlanmış Event Grid şemasını veya CloudEvents 1.0 şemasını kullanmak daha yaygındır. CloudEvents , olay verilerini ortak bir şekilde tanımlamak için belirtim oluşturan bir Cloud Native Computing Foundation projesidir. EventGridPublisherClient oluştururken konunuzun hangi şemayı kullanacak şekilde yapılandırıldığını belirtmeniz gerekir:

Konunuz Event Grid Şemasını kullanacak şekilde yapılandırılmışsa şema türü olarak "EventGrid" değerini ayarlayın:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API Key>")
);

Konunuz Bulut Olay Şeması'nı kullanacak şekilde yapılandırılmışsa şema türü olarak "CloudEvent" değerini ayarlayın:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "CloudEvent",
  new AzureKeyCredential("<API Key>")
);

Konunuz Özel Olay Şeması kullanacak şekilde yapılandırılmışsa şema türü olarak "Özel" değerini ayarlayın:

const client = new EventGridPublisherClient(
  "<endpoint>",
  "Custom",
  new AzureKeyCredential("<API Key>")
);

İstemcinin, konunun beklenecek şekilde yapılandırıldığından farklı bir şemayla yapılandırılması hizmetten bir hatayla sonuçlanır ve olaylarınız yayımlanmaz.

Aşağıdaki Azure CLI kod parçacığını kullanarak bir Event Grid konusu için hangi giriş şemasının yapılandırıldığını görebilirsiniz:

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "inputSchema"

EventGridDeserializer

Event Grid tarafından tüketicilere teslim edilen olaylar JSON olarak teslim edilir. Teslim edilen tüketicinin türüne bağlı olarak, Event Grid hizmeti tek bir yükün parçası olarak bir veya daha fazla olay teslim edebilir. Bu olaylar gibi JSON.parsenormal JavaScript yöntemleri kullanılarak seri durumdan çıkarılsa da, bu kitaplık olayları seri durumdan çıkarma için adlı EventGridDeserializerbir yardımcı türü sunar.

Doğrudan kullanımıyla JSON.parse karşılaştırıldığında, EventGridDeserializer olayları seri durumdan çıkarma sırasında bazı ek dönüştürmeler yapar:

  1. EventGridDeserializer bir olayın gerekli özelliklerinin mevcut olduğunu ve doğru türler olduğunu doğrular.
  2. EventGridDeserializer olay zamanı özelliğini JavaScript Date nesnesine dönüştürür.
  3. Bulut Olayları kullanılırken, bir olayın veri özelliği için ikili veriler kullanılabilir (kullanılarak Uint8Array). Olay Event Grid aracılığıyla gönderildiğinde, Temel 64'te kodlanır. EventGridDeserializer bu verilerin kodunu bir örneğine Uint8Arraygeri çözer.
  4. Bir Sistem Olayının (başka bir Azure hizmeti tarafından oluşturulan bir olay) deserilini kaldırdığınızda, EventGridDeserializer nesnenin data verilerini açıklayan ilgili arabirimle eşleşmesi için ek dönüştürmeler yapar. TypeScript kullanırken, bu arabirimler bir sistem olayı için veri nesnesinin özelliklerine erişirken güçlü yazma özelliğine sahip olduğunuzdan emin olun.

Örneğiniz EventGridDeserializer oluşturulurken, nesneyi daha fazla dönüştürmek için kullanılan özel seri durumdan çıkarıcılar sağlayabilirsiniz data .

Dağıtılmış İzleme ve Bulut Olayları

Bu kitaplık kullanılarak @azure/core-tracingdağıtılmış izlemeyi destekler. Dağıtılmış izleme kullanılırken, bu kitaplık bir işlem sırasında bir send yayılma alanı oluşturur. Ayrıca, Bulut Olayları 1.0 şemasını kullanarak olay gönderirken SDK, Dağıtılmış İzleme uzantısını kullanarak olaylara dağıtılmış izleme meta verileri ekler. ve tracestate uzantısı özelliklerinin değerleritraceparent, olayları gönderen HTTP isteğindeki ve tracestate üst bilgilerine karşılık gelirtraceparent. Bir olay zaten bir traceparent uzantı özelliğine sahipse güncelleştirilmez.

Kubernetes’te Event Grid

Bu kitaplık , Azure Arc kullanılarak Kubernetes'te test edilmiş ve doğrulanmıştır.

Örnekler

Event Grid Şemasını Kullanarak Bir Event Grid Konusuna Özel Olay Yayımlama

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

Event Grid Şemasını Kullanarak Event Grid Etki Alanındaki Bir Konuya Özel Olay Yayımlama

Event Grid Etki Alanında olayları yayımlamak, Event Grid Konusu'na yayımlamaya benzer, ancak olaylar için Event Grid şemasını kullanırken özelliğini eklemeniz topic gerekir. Cloud Events 1.0 şemasında olayları yayımlarken, gerekli source özellik etki alanında yayımlanması gereken konunun adı olarak kullanılır:

const { EventGridPublisherClient, AzureKeyCredential } = require("@azure/eventgrid");

const client = new EventGridPublisherClient(
  "<endpoint>",
  "EventGrid",
  new AzureKeyCredential("<API key>")
);

await client.send([
  {
    topic: "my-sample-topic",
    eventType: "Azure.Sdk.SampleEvent",
    subject: "Event Subject",
    dataVersion: "1.0",
    data: {
      hello: "world",
    },
  },
]);

Olayı Seri Durumdan Çıkarma

EventGridDeserializer Event Grid tarafından teslim edilen olayların seri durumdan çıkarılması için kullanılabilir. Bu örnekte, ne tür olaylar olduğunu algılamak için kullanılan ve isSystemEvent kullanılarak EventGridDeserializer seri durumdan çıkarılmış bir bulut olayımız vardır.

const { EventGridDeserializer, isSystemEvent } = require("@azure/eventgrid");

async function main() {
  const deserializer = new EventGridDeserializer();
  const message = {
    id: "5bc888aa-c2f4-11ea-b3de-0242ac130004",
    source:
      "/subscriptions/<subscriptionid>/resourceGroups/dummy-rg/providers/Microsoft.EventGrid/topics/dummy-topic",
    specversion: "1.0",
    type: "Microsoft.ContainerRegistry.ImagePushed",
    subject: "Test Subject",
    time: "2020-07-10T21:27:12.925Z",
    data: {
      hello: "world",
    },
  };
  const deserializedMessage = await deserializer.deserializeCloudEvents(message);
  console.log(deserializedMessage);

  if (
    deserializedMessage != null &&
    deserializedMessage.length !== 0 &&
    isSystemEvent("Microsoft.ContainerRegistry.ImagePushed", deserializedMessage[0])
  ) {
    console.log("This is a Microsoft.ContainerRegistry.ImagePushed event");
  }
}

main();

Sorun giderme

Günlüğe Kaydetme

Günlüğün etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Sonraki adımlar

Bu kitaplığın nasıl kullanılacağına ilişkin ayrıntılı örnekler için lütfen samples dizinine göz atın.

Katkıda bulunma

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.

İzlenimler