Komunikaty, ładunki i serializacja
Usługa Azure Service Bus obsługuje komunikaty. Komunikaty zawierają ładunek i metadane. Metadane są w postaci par klucz-wartość i opisują ładunek oraz zawierają instrukcje obsługi usługi Service Bus i aplikacji. Od czasu do czasu same metadane są wystarczające do przenoszenia informacji, które nadawca chce komunikować się z odbiorcami, a ładunek pozostaje pusty.
Model obiektów oficjalnych klientów usługi Service Bus dla platformy .NET i języka Java odzwierciedla abstrakcyjną strukturę komunikatów usługi Service Bus, która jest mapowana na protokoły przewodowe obsługiwane przez usługę Service Bus i z nich.
Komunikat usługi Service Bus składa się z sekcji ładunku binarnego, którą usługa Service Bus nigdy nie obsługuje w żadnej formie po stronie usługi i dwa zestawy właściwości. Właściwości brokera są wstępnie zdefiniowane przez system. Te wstępnie zdefiniowane właściwości kontrolują funkcjonalność na poziomie komunikatów wewnątrz brokera lub są mapowane na typowe i ustandaryzowane elementy metadanych. Właściwości użytkownika to kolekcja par klucz-wartość, które można zdefiniować i ustawić przez aplikację.
Wstępnie zdefiniowane właściwości brokera są wymienione w poniższej tabeli. Nazwy są używane ze wszystkimi oficjalnymi interfejsami API klienta, a także w BrokerProperties obiekcie JSON mapowania protokołu HTTP.
Równoważne nazwy używane na poziomie protokołu Advanced Message Queuing Protocol (AMQP) są wymienione w nawiasach. Podczas gdy następujące nazwy używają liter pascal, klienci JavaScript i Python będą używać odpowiednio wielkości liter wielbłądów i węża.
| Nazwa właściwości | Opis |
|---|---|
ContentType (content-type) |
Opcjonalnie opisuje ładunek komunikatu z deskryptorem w formacie RFC2045, sekcja 5; na przykład application/json. |
CorrelationId (correlation-id) |
Umożliwia aplikacji określenie kontekstu komunikatu na potrzeby korelacji; na przykład odzwierciedla identyfikator MessageId wiadomości, na którą odpowiada. |
DeadLetterSource |
Ustaw tylko w komunikatach, które zostały utracone, a później automatycznie z kolejki utraconych wiadomości do innej jednostki. Wskazuje jednostkę, w której wiadomość nie została wysłana. Ta właściwość jest tylko do odczytu. |
DeliveryCount |
Liczba dostaw, które próbowano wykonać dla tego komunikatu. Liczba jest zwiększana po wygaśnięciu blokady komunikatu lub komunikat jest jawnie porzucony przez odbiorcę. Ta właściwość jest tylko do odczytu. Liczba dostarczania nie jest zwiększana po zamknięciu bazowego połączenia AMQP. |
EnqueuedSequenceNumber |
W przypadku komunikatów, które zostały automatycznieforwardowane, ta właściwość odzwierciedla numer sekwencji, który został wcześniej przypisany do wiadomości w oryginalnym punkcie przesyłania. Ta właściwość jest tylko do odczytu. |
EnqueuedTimeUtc |
Czas UTC, w którym wiadomość została zaakceptowana i zapisana w jednostce. Tej wartości można użyć jako autorytatywnego i neutralnego wskaźnika czasu przybycia, gdy odbiorca nie chce ufać zegarowi nadawcy. Ta właściwość jest tylko do odczytu. |
ExpiresAtUtc (absolute-expiry-time) |
Czas UTC, w którym komunikat jest oznaczony do usunięcia i nie jest już dostępny do pobrania z jednostki z powodu jego wygaśnięcia. Wygaśnięcie jest kontrolowane przez właściwość TimeToLive i ta właściwość jest obliczana z enqueuedTimeUtc+TimeToLive. Ta właściwość jest tylko do odczytu. |
Label lub Subject (subject) |
Ta właściwość umożliwia aplikacji wskazanie przeznaczenia wiadomości do odbiorcy w sposób ustandaryzowany, podobnie jak wiersz tematu wiadomości e-mail. |
LockedUntilUtc |
W przypadku komunikatów pobranych w trybie blokady (zobacz tryb odbierania blokady, a nie ustawienia wstępne) ta właściwość odzwierciedla czas UTC, dopóki komunikat nie zostanie zablokowany w kolejce/subskrypcji. Po wygaśnięciu blokady parametr DeliveryCount jest zwiększany, a komunikat będzie ponownie dostępny do pobrania. Ta właściwość jest tylko do odczytu. |
LockToken |
Token blokady jest odwołaniem do blokady przechowywanej przez brokera w trybie odbierania zaglądaj za pomocą blokady . Token może służyć do przypinania blokady trwale za pośrednictwem interfejsu API odroczenia , a następnie wyprowadzania komunikatu z zwykłego przepływu stanu dostarczania. Ta właściwość jest tylko do odczytu. |
MessageId (message-id) |
Identyfikator komunikatu jest wartością zdefiniowaną przez aplikację, która jednoznacznie identyfikuje komunikat i jego ładunek. Identyfikator jest ciągiem swobodnym i może odzwierciedlać identyfikator GUID lub identyfikator pochodzący z kontekstu aplikacji. Jeśli ta opcja jest włączona, funkcja wykrywania duplikatów identyfikuje i usuwa drugie i dalsze przesyłanie komunikatów o tym samym identyfikatorze MessageId. |
PartitionKey |
W przypadku jednostek partycjonowanych ustawienie tej wartości umożliwia przypisywanie powiązanych komunikatów do tej samej partycji wewnętrznej, dzięki czemu kolejność sekwencji przesyłania jest poprawnie rejestrowana. Partycja jest wybierana przez funkcję skrótu dla tej wartości i nie można jej wybrać bezpośrednio. W przypadku jednostek obsługujących sesję właściwość SessionId zastępuje tę wartość. |
ReplyTo (reply-to) |
Ta opcjonalna i zdefiniowana przez aplikację wartość jest standardowym sposobem wyrażenia ścieżki odpowiedzi do odbiorcy komunikatu. Gdy nadawca oczekuje odpowiedzi, ustawia wartość na bezwzględną lub względną ścieżkę kolejki lub tematu, do których oczekuje się wysłania odpowiedzi. |
ReplyToSessionId (reply-to-group-id) |
Ta wartość rozszerza informacje ReplyTo i określa, które identyfikatory sesji powinny być ustawione dla odpowiedzi po wysłaniu do jednostki odpowiedzi. |
ScheduledEnqueueTimeUtc |
W przypadku komunikatów, które są udostępniane tylko do pobierania po opóźnieniu, ta właściwość definiuje moment UTC, w którym komunikat będzie logicznie kolejkowany, sekwencjonowany i w związku z tym udostępniany do pobierania. |
SequenceNumber |
Numer sekwencji jest unikatową 64-bitową liczbą całkowitą przypisaną do komunikatu, ponieważ jest akceptowana i przechowywana przez brokera oraz działa jako jej prawdziwy identyfikator. W przypadku jednostek partycjonowanych najważniejsze 16 bitów odzwierciedla identyfikator partycji. Liczby sekwencji monotonicznie zwiększają się i są bez luk. Przewracają się do 0, gdy zakres 48-64 bitów jest wyczerpany. Ta właściwość jest tylko do odczytu. |
SessionId (group-id) |
W przypadku jednostek obsługujących sesję ta wartość zdefiniowana przez aplikację określa przynależność sesji komunikatu. Komunikaty z tym samym identyfikatorem sesji podlegają blokadzie podsumowania i umożliwiają dokładne przetwarzanie w kolejności i demultiplexing. W przypadku jednostek, które nie są świadome sesji, ta wartość jest ignorowana. |
TimeToLive |
Ta wartość jest względnym czasem trwania, po upływie którego komunikat wygasa, począwszy od momentu, w którym został zaakceptowany i przechowywany przez brokera, jak przechwycono w enqueueTimeUtc. Jeśli nie ustawiono jawnie, zakładana wartość to DefaultTimeToLive dla odpowiedniej kolejki lub tematu. Wartość TimeToLive na poziomie komunikatu nie może być dłuższa niż ustawienie DefaultTimeToLive jednostki. Jeśli jest dłuższy, jest on dyskretnie dostosowywany. |
To (to) |
Ta właściwość jest zarezerwowana do użytku w przyszłości w scenariuszach routingu i obecnie ignorowana przez samego brokera. Aplikacje mogą używać tej wartości w scenariuszach automatycznego tworzenia łańcuchów opartych na regułach, aby wskazać zamierzone logiczne miejsce docelowe komunikatu. |
ViaPartitionKey |
Jeśli komunikat jest wysyłany za pośrednictwem kolejki transferu w zakresie transakcji, ta wartość wybiera partycję kolejki transferu. |
Model abstrakcyjnych komunikatów umożliwia opublikowanie komunikatu w kolejce za pośrednictwem protokołu HTTPS i można go pobrać za pośrednictwem protokołu AMQP. W obu przypadkach komunikat wygląda normalnie w kontekście odpowiedniego protokołu. Właściwości brokera są tłumaczone zgodnie z potrzebami, a właściwości użytkownika są mapowane na najbardziej odpowiednią lokalizację w odpowiednim modelu komunikatów protokołu. W przypadku protokołu HTTP właściwości użytkownika są mapowania bezpośrednio do i z nagłówków HTTP; w amQP mapują na i z application-properties mapy.
Routing i korelacja komunikatów
Podzestaw właściwości brokera opisanych wcześniej, w szczególności To, ReplyTo, , ReplyToSessionIdMessageIdCorrelationId, i SessionId, są używane do ułatwiania aplikacjom kierowania komunikatów do określonych miejsc docelowych. Aby zilustrować tę funkcję, rozważ kilka wzorców:
- Proste żądanie/odpowiedź: Wydawca wysyła wiadomość do kolejki i oczekuje odpowiedzi od odbiorcy wiadomości. Aby otrzymać odpowiedź, wydawca jest właścicielem kolejki, do której oczekuje dostarczenia odpowiedzi. Adres kolejki jest wyrażony we właściwości ReplyTo komunikatu wychodzącego. Gdy odbiorca odpowie, kopiuje identyfikator MessageId obsługiwanej wiadomości do właściwości CorrelationId komunikatu odpowiedzi i dostarcza komunikat do miejsca docelowego wskazanego przez właściwość ReplyTo. Jeden komunikat może zwracać wiele odpowiedzi w zależności od kontekstu aplikacji.
- Żądanie/odpowiedź multiemisji: jako odmiana poprzedniego wzorca wydawca wysyła wiadomość do tematu, a wielu subskrybentów kwalifikuje się do korzystania z wiadomości. Każdy z subskrybentów może odpowiedzieć w sposób opisany wcześniej. Ten wzorzec jest używany w scenariuszach odnajdywania lub rzutowania, a respondent zazwyczaj identyfikuje się z właściwością użytkownika lub wewnątrz ładunku. Jeśli funkcja ReplyTo wskazuje temat, taki zestaw odpowiedzi odnajdywania może być dystrybuowany do odbiorców.
- Multipleksowanie: ta funkcja sesji umożliwia multipleksowanie strumieni powiązanych komunikatów za pośrednictwem jednej kolejki lub subskrypcji, tak aby każda sesja (lub grupa) powiązanych komunikatów, zidentyfikowana przez pasujące wartości SessionId , są kierowane do określonego odbiornika, podczas gdy odbiorca przechowuje sesję pod blokadą. Przeczytaj więcej na temat szczegółów sesji tutaj.
- Multipleksowane żądanie/odpowiedź: ta funkcja sesji umożliwia multipleksowane odpowiedzi, dzięki czemu kilku wydawców może współużytkować kolejkę odpowiedzi. Ustawiając wartość ReplyToSessionId, wydawca może poinstruować odbiorców, aby skopiowali tę wartość do właściwości SessionId wiadomości odpowiedzi. Kolejka publikowania lub temat nie musi być świadoma sesji. W miarę wysyłania komunikatu wydawca może w szczególności czekać na sesję z danym identyfikatorem SessionId , aby zmaterializować się w kolejce, warunkowo akceptując odbiornik sesji.
Routing wewnątrz przestrzeni nazw usługi Service Bus można zrealizować przy użyciu automatycznego łańcucha łańcuchów i reguł subskrypcji tematów. Routing między przestrzeniami nazw można zrealizować przy użyciu usługi Azure LogicApps. Jak wskazano na poprzedniej liście, właściwość To jest zarezerwowana do użytku w przyszłości i może zostać ostatecznie zinterpretowana przez brokera z specjalnie włączoną funkcją. Aplikacje, które chcą zaimplementować routing, powinny to zrobić w oparciu o właściwości użytkownika, a nie na właściwości To , ale teraz nie spowodują problemów ze zgodnością.
Serializacja ładunku
Podczas przesyłania lub przechowywania wewnątrz usługi Service Bus ładunek jest zawsze nieprzezroczystym blokiem binarnym. Właściwość ContentType umożliwia aplikacjom opisywanie ładunku z sugerowanym formatem wartości właściwości będących opisem typu zawartości MIME zgodnie z RFC2045 IETF, na przykład application/json;charset=utf-8.
W przeciwieństwie do wariantów języka Java lub .NET Standard wersja .NET Framework interfejsu API usługi Service Bus obsługuje tworzenie wystąpień brokeredMessage przez przekazanie dowolnych obiektów platformy .NET do konstruktora.
30 września 2026 r. wycofamy biblioteki zestawu SDK usługi Azure Service Bus WindowsAzure.ServiceBus, Microsoft.Azure.ServiceBus i com.microsoft.azure.servicebus, które nie są zgodne z wytycznymi dotyczącymi zestawu Azure SDK. Zakończymy również obsługę protokołu SBMP, więc nie będzie można już używać tego protokołu po 30 września 2026 r. Przeprowadź migrację do najnowszych bibliotek zestawu Azure SDK, które oferują krytyczne aktualizacje zabezpieczeń i ulepszone możliwości przed tą datą.
Mimo że starsze biblioteki mogą być nadal używane poza 30 września 2026 r., nie będą już otrzymywać oficjalnej pomocy technicznej i aktualizacji od firmy Microsoft. Aby uzyskać więcej informacji, zobacz ogłoszenie o wycofaniu pomocy technicznej.
W przypadku korzystania ze starszego protokołu SBMP te obiekty są następnie serializowane z domyślnym serializatorem binarnym lub serializatorem dostarczanym zewnętrznie. Obiekt jest serializowany do obiektu AMQP. Odbiornik może pobrać te obiekty za pomocą GetBody\<T>() metody , podając oczekiwany typ. W przypadku protokołu AMQP obiekty są serializowane w grafie ArrayList protokołu AMQP obiektów i IDictionary<string,object> , a każdy klient amQP może je dekodować.
30 września 2026 r. wycofamy obsługę protokołu SBMP dla usługi Azure Service Bus, więc nie będzie można już używać tego protokołu po 30 września 2026 r. Przeprowadź migrację do najnowszych bibliotek zestawu SDK usługi Azure Service Bus przy użyciu protokołu AMQP, który oferuje krytyczne aktualizacje zabezpieczeń i ulepszone możliwości przed tą datą.
Aby uzyskać więcej informacji, zobacz ogłoszenie o wycofaniu pomocy technicznej.
Chociaż ta ukryta magia serializacji jest wygodna, aplikacje powinny przejąć jawną kontrolę nad serializacji obiektów i przekształcić ich grafy obiektów w strumienie przed dołączeniem ich do komunikatu i zrobić odwrotnie po stronie odbiornika. Daje to wyniki współdziałania. Chociaż protokół AMQP ma zaawansowany model kodowania binarnego, jest powiązany z ekosystemem obsługi komunikatów AMQP, a klienci HTTP mają problemy z dekodowaniem takich ładunków.
Warianty interfejsu API .NET Standard i Java akceptują tylko tablice bajtów, co oznacza, że aplikacja musi obsługiwać kontrolkę serializacji obiektów.
Podczas obsługi deserializacji obiektów z ładunku komunikatów deweloperzy powinni wziąć pod uwagę, że komunikaty mogą pochodzić z wielu źródeł przy użyciu różnych metod serializacji. Może się to również zdarzyć w przypadku ewolucji pojedynczej aplikacji, gdzie stare wersje mogą nadal działać wraz z nowszymi wersjami. W takich przypadkach zaleca się stosowanie dodatkowych metod deserializacji, aby spróbować, jeśli pierwsza próba deserializacji nie powiedzie się. Jedną z bibliotek obsługujących tę funkcję jest NServiceBus. Jeśli wszystkie metody deserializacji kończą się niepowodzeniem, zaleca się, aby komunikat został utracony.
Następne kroki
Aby dowiedzieć się więcej o komunikatach usługi Service Bus, zobacz następujące tematy: