Udostępnij za pośrednictwem

Biblioteka klienta usługi Azure Event Grid dla języka JavaScript — wersja 5.5.1

  • Artykuł

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

Użyj biblioteki klienta, aby:

  • Wysyłanie zdarzeń do usługi Event Grid przy użyciu schematów usługi Event Grid, zdarzeń chmury 1.0 lub schematu niestandardowego
  • Dekodowanie i przetwarzanie zdarzeń, 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

Kluczowe linki:

  • kod źródłowy
  • pakietu (NPM)
  • Dokumentacja referencyjna interfejs u API
  • dokumentacja produktu
  • przykładów

Wprowadzenie

Obecnie obsługiwane środowiska

  • wersje Node.js LTS
  • Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

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

Warunki wstępne

Jeśli używasz interfejsu wiersza polecenia platformy Azure, zastąp <your-resource-group-name> 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 usługi Azure Event Grid dla języka JavaScript przy użyciu 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, będzie potrzebny endpoint tematu usługi Event Grid i 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 kodu interfejsu 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ć klasy AzureKeyCredential do uwierzytelniania klienta w następujący sposób:

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

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

Korzystanie z tokenu SAS

Podobnie jak klucz dostępu, token SAS 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 ponownego wygenerowania, token SAS ma czas eksploracji, w którym momencie nie jest już prawidłowy. Aby użyć tokenu SAS do uwierzytelniania, użyj AzureSASCredential w następujący sposób:

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 funkcji generateSharedAccessSigniture.

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ą usługi Azure AD możesz użyć kontroli dostępu opartej na rolach (RBAC), aby udzielić dostępu do zasobów usługi Azure Event Grid użytkownikom, grupom lub aplikacjom.

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

Pakiet @azure/identity 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 README.

Na przykład można użyć DefaultAzureCredential do utworzenia 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 wysyłanie 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. Po utworzeniu 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 jest częściej używany już zdefiniowany schemat usługi Event Grid lub schematu CloudEvents 1.0. CloudEvents to projekt Cloud Native Computing Foundation, który tworzy specyfikację opisującą dane 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 przy użyciu innego schematu niż oczekiwana konfiguracja tematu spowoduje wystąpienie błędu z usługi, a zdarzenia nie zostaną opublikowane.

Zobaczysz, jaki schemat wejściowy został skonfigurowany dla tematu usługi Event Grid, korzystając z poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure 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 dostarczanego odbiorcy usługa Event Grid może dostarczać co najmniej jedno zdarzenie w ramach jednego ładunku. Chociaż te zdarzenia mogą być deserializowane 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 wykonuje kilka dodatkowych konwersji 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 Date języka JavaScript.
  3. W przypadku korzystania ze zdarzeń w chmurze dane binarne mogą być używane dla właściwości danych zdarzenia (przy użyciu Uint8Array). Gdy zdarzenie jest wysyłane za pośrednictwem usługi Event Grid, jest ono kodowane w bazie 64. EventGridDeserializer zdekoduje te dane z powrotem do wystąpienia Uint8Array.
  4. Podczas deserializacji zdarzeń systemu (zdarzenia wygenerowanego przez inną usługę platformy Azure) wykona dodatkowe konwersje, tak aby obiekt był zgodny z odpowiednim interfejsem, który opisuje 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 można podać niestandardowe deserializatory, które są używane do dalszej konwersji obiektu data.

Śledzenie rozproszone i zdarzenia w chmurze

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

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 uwzględnić właściwość topic. Podczas publikowania zdarzeń w schemacie Cloud Events 1.0 wymagana właściwość source 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 mogą służyć do deserializacji zdarzeń dostarczanych przez usługę Event Grid. W tym przykładzie mamy zdarzenie w chmurze, które zostało zdeserializowane przy użyciu EventGridDeserializer i użyjemy isSystemEvent w celu wykrycia typu zdarzeń, które są.

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

Wyrąb

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @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 pakietu @azure/rejestratora.

Następne kroki

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

Przyczyniając się

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

wrażenia