Udostępnij za pośrednictwem

Przestrzenie nazw usługi Azure Event Grid — obsługa schematu CloudEvents

  • Artykuł

Tematy dotyczące przestrzeni nazw usługi Event Grid akceptują zdarzenia zgodne z otwartą standardową specyfikacją CloudEvents CloudEvents 1.0 przy użyciu powiązania protokołu HTTP z formatem JSON. CloudEvent to rodzaj komunikatu, który zawiera informacje, które są przekazywane, nazywane danymi zdarzenia i metadanymi. Dane zdarzenia w architekturach opartych na zdarzeniach zwykle zawierają informacje ogłaszające zmianę stanu systemu. Metadane CloudEvents składają się z zestawu atrybutów, które zapewniają kontekstowe informacje o wiadomości, takie jak miejsce jego utworzenia (system źródłowy), jego typ itp. Wszystkie prawidłowe komunikaty zgodne ze specyfikacjami CloudEvents muszą zawierać następujące wymagane atrybuty kontekstu:

Specyfikacja CloudEvents definiuje również opcjonalne i rozszerzenia atrybuty kontekstu, które można uwzględnić podczas korzystania z usługi Event Grid.

W przypadku korzystania z usługi Event Grid usługa CloudEvents jest preferowanym formatem zdarzeń ze względu na dobrze udokumentowane przypadki użycia (tryby przesyłania zdarzeń, formatów zdarzeń itp.), rozszerzalność i ulepszoną współdziałanie. Rozwiązanie CloudEvents poprawia współdziałanie, zapewniając wspólny format zdarzeń do publikowania i korzystania z zdarzeń. Umożliwia to jednolite narzędzia i standardowe sposoby routingu i obsługi zdarzeń.

CloudEvents con tryb namiotu s

Specyfikacja CloudEvents definiuje trzy con tryb namiotu s: binarne, ustrukturyzowane i wsadowe.

Ważne

Z dowolnym con tryb namiotu można wymieniać tekst (JSON, tekst/*itp.) lub dane zdarzenia zakodowane binarnie. Plik binarny con tryb namiotu nie jest używany wyłącznie do wysyłania danych binarnych.

Con tryb namiotu s nie dotyczy kodowania używanego, binarnego lub tekstowego, ale o tym, jak są opisywane i wymieniane dane zdarzenia i jego metadane. Struktura con tryb namiotu używa pojedynczej struktury, na przykład obiektu JSON, gdzie zarówno atrybuty kontekstu, jak i dane zdarzenia są razem w ładunku HTTP. Binarny con tryb namiotu oddziela atrybuty kontekstu, które są mapowane na nagłówki HTTP i dane zdarzeń, które są ładunkiem HTTP zakodowanym zgodnie z typem nośnika ustawionym w pliku Content-Type.

Obsługa rozwiązania CloudEvents

W tej tabeli przedstawiono bieżącą obsługę specyfikacji CloudEvents:

CloudEvents con tryb namiotu Obsługiwane?
Ustrukturyzowany kod JSON Tak
Dane JSON ze strukturą wsadowe Tak, w przypadku zdarzeń publikowania
Dwójkowy Tak, w przypadku zdarzeń publikowania

Maksymalny dozwolony rozmiar zdarzenia to 1 MB. Zdarzenia powyżej 64 KB są naliczane w przyrostach 64 KB.

Konsrukturyzowane tryb namiotu

Komunikat w usłudze CloudEvents ze strukturą con tryb namiotu zawiera zarówno atrybuty kontekstu, jak i dane zdarzenia w ładunku HTTP.

Ważne

Obecnie usługa Event Grid obsługuje format JSON CloudEvents z protokołem HTTP.

Oto przykład rozwiązania CloudEvents w trybie ustrukturyzowanym przy użyciu formatu JSON. Oba metadane (wszystkie atrybuty, które nie są "danymi"), a dane komunikatu/zdarzenia (obiekt "dane") są opisane przy użyciu formatu JSON. Nasz przykład zawiera wszystkie wymagane atrybuty kontekstu wraz z niektórymi atrybutami opcjonalnymi (subject, time, i ) i datacontenttypeatrybutami rozszerzenia (comexampleextension1, comexampleothervalue).

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "subject" : "O-28964",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "comexampleextension1" : "value",
    "comexampleothervalue" : 5,
    "datacontenttype" : "application/json",
    "data" : {
       "orderId" : "O-28964",
       "URL" : "https://com.yourcompany/orders/O-28964"
    }
}

Format JSON z zawartością ustrukturyzowaną umożliwia wysyłanie danych zdarzeń, które nie są wartością JSON. W tym celu należy wykonać następujące czynności:

  1. Dołącz atrybut z typem datacontenttype nośnika, w którym dane są kodowane.
  2. Jeśli typ nośnika jest zakodowany w formacie tekstowym, na przykład text/plain, text/csvlub application/xml, należy użyć data atrybutu z ciągiem JSON zawierającym to, co komunikujesz jako wartość.
  3. Jeśli typ nośnika reprezentuje kodowanie binarne, należy użyć data_base64 atrybutu, którego wartość jest ciągiem JSON zawierającym zakodowaną wartość binarną BASE64.

Na przykład to rozwiązanie CloudEvent przenosi dane zdarzenia zakodowane w programie w application/protobuf celu wymiany komunikatów Protobuf.

{
    "specversion" : "1.0",
    "type" : "com.yourcompany.order.created",
    "source" : "/orders/account/123",
    "id" : "A234-1234-1234",
    "time" : "2018-04-05T17:31:00Z",
    "datacontenttype" : "application/protobuf",
    "data_base64" : "VGhpcyBpcyBub3QgZW5jb2RlZCBpbiBwcm90b2J1ZmYgYnV0IGZvciBpbGx1c3RyYXRpb24gcHVycG9zZXMsIGltYWdpbmUgdGhhdCBpdCBpcyA6KQ=="
}

Aby uzyskać więcej informacji na temat używania atrybutów data lub data_base64 , zobacz Obsługa danych .

Aby uzyskać więcej informacji na temat tego con tryb namiotu, zobacz CloudEvents HTTP structured con tryb namiotu specifications .

Batched con tryb namiotu

Usługa Event Grid obsługuje obecnie kod JSON wsadowy con tryb namiotu podczas publikowania usługi CloudEvents w usłudze Event Grid. Ten con tryb namiotu używa tablicy JSON wypełnionej biblioteką CloudEvents w strukturze con tryb namiotu. Na przykład aplikacja może publikować dwa zdarzenia przy użyciu tablicy podobnej do poniższej. Podobnie jeśli używasz zestawu SDK płaszczyzny danych usługi Event Grid, ten ładunek jest również wysyłany:

[
    {
        "specversion": "1.0",
        "id": "E921-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": "some data"
    },
    {
        "specversion": "1.0",
        "id": "F555-1234-1235",
        "source": "/mycontext",
        "type": "com.example.someeventtype",
        "time": "2018-04-05T17:31:00Z",
        "data": {
            "somekey" : "value",
            "someOtherKey" : 9
        }
    }
]

Aby uzyskać więcej informacji, zobacz CloudEvents Batched Content Mode specs (Specyfikacje trybu zawartości wsadowej w usłudze CloudEvents).

Dzielenie na partie

Aplikacja powinna wsadować kilka zdarzeń razem w tablicy, aby uzyskać większą wydajność i większą przepływność przy użyciu pojedynczego żądania publikowania. Partie mogą wynosić do 1 MB, a maksymalny rozmiar zdarzenia to 1 MB.

Binarne con tryb namiotu

Element CloudEvent w pliku binarnym con tryb namiotu ma atrybuty kontekstu opisane jako nagłówki HTTP. Nazwy nagłówków HTTP są nazwą atrybutu kontekstu poprzedzonego prefiksem ce-. Nagłówek Content-Type odzwierciedla typ nośnika, w którym dane zdarzenia są kodowane.

Ważne

W przypadku korzystania z pliku binarnego con tryb namiotu ce-datacontenttype nagłówek HTTP NIE MOŻE być również obecny.

Ważne

Jeśli planujesz uwzględnić własne atrybuty (tj. atrybuty rozszerzenia) podczas używania znaku binarnego con tryb namiotu, upewnij się, że ich nazwy składają się z małych liter ("a" do "z") lub cyfr ('0' do '9') z znaku ASCII i że nie przekraczają 20 znaków. Oznacza to, że konwencja nazewnictwa atrybutów kontekstu CloudEvents jest bardziej restrykcyjna niż w przypadku prawidłowych nazw nagłówków HTTP. Nie każda prawidłowa nazwa nagłówka HTTP jest prawidłową nazwą atrybutu rozszerzenia.

Ładunek HTTP to dane zdarzenia zakodowane zgodnie z typem nośnika w pliku Content-Type.

Żądanie HTTP używane do publikowania elementu CloudEvent w trybie binarnym zawartości może wyglądać następująco:

POST / HTTP/1.1
HOST mynamespace.eastus-1.eventgrid.azure.net/topics/mytopic
ce-specversion: 1.0
ce-type: com.example.someevent
ce-source: /mycontext
ce-id: A234-1234-1234
ce-time: 2018-04-05T17:31:00Z
ce-comexampleextension1: value
ce-comexampleothervalue: 5
content-type: application/protobuf

Binary data according to protobuf encoding format. No context attributes are included.

Kiedy należy używać konsumentu binarnego lub strukturalnego rozwiązania CloudEvents tryb namiotu

Możesz użyć struktury con tryb namiotu jeśli potrzebujesz prostego podejścia do przekazywania rozwiązania CloudEvents między przeskokami i protokołami. Ponieważ rozwiązanie CloudEvent w strukturze con tryb namiotu zawiera komunikat wraz z metadanymi, łatwo jest klientom używać go jako całości i przekazywać go do innych systemów.

Możesz użyć funkcji con tryb namiotu jeśli wiesz, że aplikacje podrzędne wymagają tylko komunikatu bez dodatkowych informacji (czyli atrybutów kontekstu). Mimo że ze strukturą con tryb namiotu nadal można pobrać dane zdarzenia (komunikat) z rozwiązania CloudEvent, łatwiej jest, jeśli aplikacja konsumenta po prostu znajduje się w ładunku HTTP. Na przykład inne aplikacje mogą używać innych protokołów i mogą być zainteresowane tylko podstawowym komunikatem, a nie jego metadanymi. W rzeczywistości metadane mogą być istotne tylko dla natychmiastowego pierwszego przeskoku. W takim przypadku posiadanie danych, które mają być wymieniane poza jego metadanymi, ułatwia obsługę i przekazywanie.

Powiązana zawartość