Rest API-referens för Azure Web PubSub-tjänstens dataplan

Som illustreras av arbetsflödesdiagrammet ovan och även detaljerade arbetsflöden som beskrivs internt, kan appservern skicka meddelanden till klienter eller hantera anslutna klienter med hjälp av REST-API:er som exponeras av Web PubSub-tjänsten. I den här artikeln beskrivs REST-API:erna i detalj.

Viktigt!

Råa anslutningssträng visas endast i den här artikeln i demonstrationssyfte.

En reťazec pripojenia inkluderar den auktoriseringsinformation som din applikation behöver för att få tillgång till Azure Web PubSub-tjänsten. Accessnyckeln i reťazec pripojenia fungerar som ett root-lösenord för din tjänst. Skydda alltid dina åtkomstnycklar i produktionsmiljöer. Använd Azure Key Vault för att hantera och rotera dina nycklar på ett säkert sätt och skydda anslutningen med WebPubSubServiceClient.

Undvik att distribuera åtkomstnycklar till andra användare, hårdkoda dem eller spara dem var som helst i oformaterad text som är tillgänglig för andra. Rotera dina nycklar om du tror att de har komprometterats.

Använda REST-API

Gruppnamn och användar-ID i förfrågningsvägar

REST-operationer som inkluderar ett gruppnamn eller användar-ID i förfrågningsvägen har en begränsning med framåtriktade snedstreck (/) i dessa värden. URL-kodning av snedstrecket som %2F kanske inte löser begränsningen: operationen kan misslyckas med att adressera den avsedda gruppen eller användaren. Till exempel kan en klient kopplad till användar-ID: tenant/alice t inte hittas av en REST-förfrågan vars väg innehåller /users/tenant%2Falice.

Denna begränsning gäller för operationer som använder dessa vägparametrar, såsom att skicka meddelanden, kontrollera om en grupp eller användare finns, stänga anslutningar och hantera gruppmedlemskap. Server-SDK-metoder som anropar dessa REST-endpoints omfattas av samma begränsning. Detta är en begränsning av REST-begäran-vägar, inte ett allmänt förbud mot / gruppnamn eller användar-ID i Web PubSub.

För att undvika begränsningen, använd gruppnamn och användar-ID utan / när din applikation behöver dessa REST-operationer. Om din applikations identifierare innehåller /, mappar dem till unika, snedstreckfria identifierare och använd de mappade värdena konsekvent i klientåtkomsttokens, gruppmedlemskap och REST-anrop. Att endast ändra värdet i REST-förfrågan ändrar inte användar-ID eller gruppnamn kopplat till en befintlig anslutning.

Anmärkning

Ett 202 Accepted svar från en sändningsoperation indikerar att förfrågan accepterades för bearbetning. Den bekräftar inte leverans till den avsedda användaren eller gruppen.

Autentisera via Azure Web PubSub Service AccessKey

I varje HTTP-begäran krävs en auktoriseringsrubrik med en JSON-webbtoken (JWT) för att autentisera med Azure Web PubSub Service.

Signeringsalgoritm och signatur

HS256, nämligen HMAC-SHA256, används som signeringsalgoritm.

Du bör använda AccessKey reťazec pripojenia i Azure Web PubSub Service-instansen för att signera den genererade JWT.

Anspråk

Nedanstående krav måste inkluderas i JWT.

Anspråkstyp	Krävs	beskrivning
aud	true	Bör vara SAMMA som URL:en för DIN HTTP-begäran. En sändningsförfrågans målgrupp ser till exempel ut så här: https://example.webpubsub.azure.com/api/hubs/myhub/:send?api-version=2022-11-01.
exp	true	Epoktid när denna token kommer att upphöra att gälla.

En pseudokod i JS:

Råa anslutningssträng visas endast i den här artikeln i demonstrationssyfte. Skydda alltid dina åtkomstnycklar i produktionsmiljöer. Använd Azure Key Vault för att hantera och rotera dina nycklar på ett säkert sätt och skydda anslutningen med WebPubSubServiceClient.

const bearerToken = jwt.sign({}, connectionString.accessKey, {
  audience: request.url,
  expiresIn: "1h",
  algorithm: "HS256",
});

Autentisera via Microsoft Entra-token

Precis som med hjälp av AccessKeykrävs även en JSON-webbtoken (JWT) för att autentisera HTTP-begäran.

Skillnaden är att i detta scenario genereras JWT av Microsoft Entra ID.

Lär dig hur du genererar Microsoft Entra-token

Omfånget för autentiseringsuppgifter ska vara https://webpubsub.azure.com/.default.

Du kan också använda rollbaserad åtkomstkontroll (RBAC) för att auktorisera begäran från servern till Azure Web PubSub Service.

Lär dig hur du lägger till rolltilldelningar

API:er

Åtgärdsgrupp	beskrivning
Tjänststatus	Tillhandahåller åtgärder för att kontrollera tjänststatusen
REST-operationer	Tillhandahåller åtgärder för att hantera anslutningarna och skicka meddelanden till dem.