biblioteka klienta Azure Event Grid dla języka JavaScript — wersja 5.4.0

  • Artykuł

Azure Event Grid to usługa oparta na chmurze, która zapewnia niezawodne dostarczanie zdarzeń na ogromną skalę.

Użyj biblioteki klienta, aby:

  • Wysyłanie zdarzeń do usługi Event Grid przy użyciu schematów usługi Event Grid, zdarzeń w chmurze 1.0 lub schematu niestandardowego
  • Dekoduj i przetwarzaj zdarzenia, które zostały dostarczone do programu obsługi usługi Event Grid
  • Generowanie sygnatur dostępu współdzielonego dla tematów usługi Event Grid

Linki kluczowe:

Wprowadzenie

Obecnie obsługiwane środowiska

Aby uzyskać więcej informacji, zobacz nasze zasady pomocy technicznej .

Wymagania wstępne

Jeśli używasz interfejsu wiersza polecenia platformy Azure, zastąp <your-resource-group-name> wartości i <your-resource-name> własnymi unikatowymi nazwami:

Tworzenie tematu usługi Event Grid

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

Tworzenie domeny usługi Event Grid

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

Instalowanie pakietu @azure/eventgrid

Zainstaluj bibliotekę klienta Azure Event Grid dla języka JavaScript przy użyciu polecenia npm:

npm install @azure/eventgrid

Tworzenie i uwierzytelnianie EventGridPublisherClient

Aby utworzyć obiekt klienta w celu uzyskania dostępu do interfejsu API usługi Event Grid, potrzebujesz endpoint tematu usługi Event Grid i elementu credential. Klient usługi Event Grid może używać klucza dostępu lub sygnatury dostępu współdzielonego utworzonego na podstawie klucza dostępu.

Punkt końcowy tematu usługi Event Grid można znaleźć w witrynie Azure Portal lub przy użyciu poniższego fragmentu wiersza polecenia platformy Azure :

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

Używanie klucza dostępu

Użyj witryny Azure Portal , aby przejść do zasobu usługi Event Grid i pobrać klucz dostępu lub użyć poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure :

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

Po utworzeniu klucza interfejsu API i punktu końcowego możesz użyć AzureKeyCredential klasy , aby uwierzytelnić klienta w następujący sposób:

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

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

Używanie tokenu SAS

Podobnie jak klucz dostępu, token SYGNATURy dostępu współdzielonego umożliwia dostęp do wysyłania zdarzeń do tematu usługi Event Grid. W przeciwieństwie do klucza dostępu, który może być używany do momentu jego ponownego wygenerowania, token SYGNATURy dostępu współdzielonego ma czas eksplodacji, w którym momencie nie jest już prawidłowy. Aby użyć tokenu SAS do uwierzytelniania, użyj następującego AzureSASCredential polecenia:

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

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

Token SAS można wygenerować przy użyciu generateSharedAccessSigniture funkcji .

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")
);

Korzystanie z usługi Azure Active Directory (AAD)

Usługa Azure EventGrid zapewnia integrację z usługą Azure Active Directory (Azure AD) na potrzeby uwierzytelniania opartego na tożsamościach żądań. Za pomocą Azure AD można użyć kontroli dostępu opartej na rolach (RBAC) w celu udzielenia dostępu do zasobów Azure Event Grid użytkownikom, grupom lub aplikacjom.

Aby wysyłać zdarzenia do tematu lub domeny za pomocą TokenCredentialelementu , tożsamość uwierzytelniona powinna mieć przypisaną rolę "Nadawca danych usługi EventGrid".

@azure/identity Pakiet umożliwia bezproblemowe autoryzowanie żądań zarówno w środowiskach deweloperskich, jak i produkcyjnych. Aby dowiedzieć się więcej o usłudze Azure Active Directory, zobacz @azure/identity PLIK README.

Na przykład można użyć polecenia DefaultAzureCredential , aby skonstruować klienta, który będzie uwierzytelniany przy użyciu usługi Azure Active Directory:

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

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

Kluczowe pojęcia

EventGridPublisherClient

EventGridPublisherClient Służy do wysyłania zdarzeń do tematu usługi Event Grid lub domeny usługi Event Grid.

Schematy zdarzeń

Usługa Event Grid obsługuje wiele schematów dla zdarzeń kodowania. Podczas tworzenia tematu niestandardowego lub domeny należy określić schemat, który będzie używany podczas publikowania zdarzeń. Chociaż temat można skonfigurować tak, aby używał schematu niestandardowego , częściej używa się już zdefiniowanego schematu usługi Event Grid lub schematu CloudEvents 1.0. CloudEvents to projekt Cloud Native Computing Foundation, który tworzy specyfikację do opisywania danych zdarzeń w typowy sposób. Podczas konstruowania klasy EventGridPublisherClient należy określić, który schemat tematu jest skonfigurowany do użycia:

Jeśli temat jest skonfigurowany do używania schematu usługi Event Grid, ustaw wartość "EventGrid" jako typ schematu:

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

Jeśli temat jest skonfigurowany do używania schematu zdarzeń w chmurze, ustaw wartość "CloudEvent" jako typ schematu:

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

Jeśli temat jest skonfigurowany do używania niestandardowego schematu zdarzeń, ustaw wartość "Niestandardowy" jako typ schematu:

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

Konstruowanie klienta z innym schematem niż oczekiwany temat spowoduje błąd usługi, a zdarzenia nie zostaną opublikowane.

Możesz zobaczyć, jaki schemat wejściowy został skonfigurowany dla tematu usługi Event Grid, korzystając z poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure :

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

EventGridDeserializer

Zdarzenia dostarczane użytkownikom przez usługę Event Grid są dostarczane jako dane JSON. W zależności od typu odbiorcy dostarczanego do usługi Event Grid może dostarczyć co najmniej jedno zdarzenie w ramach jednego ładunku. Chociaż te zdarzenia mogą zostać zdeserializowane przy użyciu normalnych metod języka JavaScript, takich jak JSON.parse, ta biblioteka oferuje typ pomocnika do deserializacji zdarzeń o nazwie EventGridDeserializer.

W porównaniu z użyciem JSON.parse bezpośrednio EventGridDeserializer program wykonuje pewne dodatkowe konwersje podczas deserializacji zdarzeń:

  1. EventGridDeserializer Sprawdza, czy wymagane właściwości zdarzenia są obecne i są właściwymi typami.
  2. EventGridDeserializer Konwertuje właściwość czasu zdarzenia na obiekt JavaScript Date .
  3. W przypadku korzystania ze zdarzeń w chmurze dane binarne mogą być używane dla właściwości danych zdarzenia (przy użyciu polecenia Uint8Array). Gdy zdarzenie jest wysyłane za pośrednictwem usługi Event Grid, jest zakodowane w bazie 64. EventGridDeserializer spowoduje dekodowanie tych danych z powrotem do wystąpienia klasy Uint8Array.
  4. Podczas deserializacji zdarzenia systemowego (zdarzenia wygenerowanego przez inną usługę platformy Azure) EventGridDeserializer wykona dodatkowe konwersje, tak aby data obiekt był zgodny z odpowiednim interfejsem opisującym jego dane. W przypadku korzystania z języka TypeScript te interfejsy zapewniają silne wpisywanie podczas uzyskiwania dostępu do właściwości obiektu danych dla zdarzenia systemowego.

Podczas tworzenia wystąpienia EventGridDeserializer programu można podać niestandardowe deserializatory, które są używane do dalszej konwersji data obiektu.

Śledzenie rozproszone i zdarzenia w chmurze

Ta biblioteka obsługuje śledzenie rozproszone przy użyciu polecenia @azure/core-tracing. W przypadku korzystania z śledzenia rozproszonego ta biblioteka utworzy zakres podczas send operacji. Ponadto podczas wysyłania zdarzeń przy użyciu schematu zdarzeń w chmurze 1.0 zestaw SDK doda metadane śledzenia rozproszonego do zdarzeń przy użyciu rozszerzenia Rozproszone śledzenie. Wartości traceparent właściwości rozszerzenia i tracestate odpowiadają traceparent nagłówkom i tracestate z żądania HTTP, które wysyła zdarzenia. Jeśli zdarzenie ma traceparent już właściwość rozszerzenia, nie została zaktualizowana.

Usługa Event Grid na platformie Kubernetes

Ta biblioteka została przetestowana i zweryfikowana na platformie Kubernetes przy użyciu usługi Azure Arc.

Przykłady

Publikowanie zdarzenia niestandardowego w temacie usługi Event Grid przy użyciu schematu usługi Event Grid

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",
    },
  },
]);

Publikowanie zdarzenia niestandardowego w temacie w domenie usługi Event Grid przy użyciu schematu usługi Event Grid

Publikowanie zdarzeń w domenie usługi Event Grid jest podobne do publikowania w temacie usługi Event Grid, z tą różnicą, że w przypadku używania schematu usługi Event Grid dla zdarzeń należy dołączyć topic właściwość . Podczas publikowania zdarzeń w schemacie Cloud Events 1.0 wymagana source właściwość jest używana jako nazwa tematu w domenie do opublikowania w:

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",
    },
  },
]);

Deserializowanie zdarzenia

EventGridDeserializer może służyć do deserializacji zdarzeń dostarczanych przez usługę Event Grid. W tym przykładzie mamy zdarzenie w chmurze, które jest deserializowane przy użyciu i EventGridDeserializer służy isSystemEvent do wykrywania typu zdarzeń.

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();

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel polecenie w pliku @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietu @azure/rejestratora.

Następne kroki

Zapoznaj się z katalogiem samples , aby zapoznać się ze szczegółowymi przykładami dotyczącymi korzystania z tej biblioteki.

Współtworzenie

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

Wrażenia