Az Azure Functions fejlesztése és konfigurálása az Azure SignalR szolgáltatással

Az Azure Functions-alkalmazások az Azure SignalR Szolgáltatás kötéseivel valós idejű képességeket adhatnak hozzá. Az ügyfélalkalmazások több nyelven elérhető ügyféloldali SDK-kkal csatlakoznak az Azure SignalR Szolgáltatáshoz, és valós idejű üzeneteket fogadnak.

Ez a cikk a SignalR Szolgáltatással integrált Azure-függvényalkalmazások fejlesztésének és konfigurálásának alapelveit ismerteti.

SignalR-szolgáltatás konfigurálása

Az Azure SignalR Szolgáltatás különböző módokon konfigurálható. Az Azure Functions használatakor a szolgáltatást kiszolgáló nélküli módban kell konfigurálni.

Az Azure Portalon keresse meg a SignalR-szolgáltatás erőforrásának Beállítások lapját. Állítsa a Szolgáltatás módot kiszolgáló nélkülire.

Az Azure Functions fejlesztése

Az Azure Functions és az Azure SignalR szolgáltatással készült kiszolgáló nélküli valós idejű alkalmazásokhoz legalább két Azure-függvény szükséges:

• Egy negotiate függvény, amelyet az ügyfél egy érvényes SignalR-szolgáltatás hozzáférési jogkivonatának és végponti URL-címének beszerzéséhez hív meg.
• Egy vagy több függvény, amely kezeli a SignalR Szolgáltatásból az ügyfeleknek küldött üzeneteket.

Egyeztetési függvény

Az ügyfélalkalmazások érvényes hozzáférési jogkivonatot igényelnek az Azure SignalR Service-hez való csatlakozáshoz. A hozzáférési jogkivonatok névtelenek lehetnek, vagy hitelesíthetők egy felhasználói azonosítóval. A kiszolgáló nélküli SignalR-szolgáltatásalkalmazásokhoz jogkivonat és egyéb kapcsolati adatok, például a SignalR-szolgáltatás végpontJÁNAK URL-címe lekéréséhez http-végpont szükséges negotiate .

A kapcsolati információs objektum létrehozásához használjon HTTP-aktivált Azure-függvényt és bemeneti SignalRConnectionInfo kötést. A függvénynek http-útvonalon kell végződnie /negotiate.

A C# osztályalapú modellel nincs szüksége a SignalRConnectionInfo bemeneti kötésre, és sokkal egyszerűbben adhat hozzá egyéni jogcímeket. További információ: Tárgyalási élmény az osztályalapú modellben.

A függvényről további információt az negotiate Azure Functions fejlesztése című témakörben talál.

A hitelesített jogkivonatok létrehozásáról az App Service-hitelesítés használata című témakörben olvashat.

A SignalR szolgáltatásból küldött üzenetek kezelése

A kötés használatával kezelheti a SignalRTrigger SignalR szolgáltatásból küldött üzeneteket. Értesítést kaphat, ha az ügyfelek üzeneteket küldenek, vagy az ügyfelek csatlakoznak vagy megszakadnak.

További információ: SignalR Service trigger kötési referenciája.

A függvényvégpontot felsőbb rétegbeli végpontként is konfigurálnia kell, hogy a szolgáltatás aktiválja a függvényt, amikor egy ügyfél üzenete irányítja. A felsőbb rétegbeli végpontok konfigurálásáról további információt a felsőbb rétegbeli végpontok című témakörben talál.

Feljegyzés

A SignalR szolgáltatás nem támogatja az StreamInvocation ügyfél kiszolgáló nélküli módban érkező üzenetét.

Üzenetek küldése és csoporttagság kezelése

SignalR A kimeneti kötés használatával üzeneteket küldhet az Azure SignalR Service-hez csatlakozó ügyfeleknek. Az összes ügyfélnek küldhet üzeneteket, vagy elküldheti őket az ügyfelek egy részhalmazának. Például csak egy adott felhasználói azonosítóval hitelesített ügyfeleknek vagy csak egy adott csoportnak küldhet üzeneteket.

A felhasználók egy vagy több csoporthoz is hozzáadhatók. A kimeneti kötés használatával SignalR felhasználókat is felvehet vagy eltávolíthat csoportokba vagy csoportokból.

További információ: kimeneti SignalR kötés referenciája.

SignalR Hubs

A SignalR a hubok fogalmával rendelkezik. Az Egyes ügyfélkapcsolatok és az Azure Functionsből küldött üzenetek hatóköre egy adott központra terjed ki. A központokkal logikai névterekre bonthatja a kapcsolatokat és az üzeneteket.

Osztályalapú modell

Az osztályalapú modell a C# számára van dedikáltan.

Izolált feldolgozói modell

Az osztályalapú modell jobb programozási élményt biztosít, amely képes lecserélni a SignalR bemeneti és kimeneti kötéseit a következő funkciókra:

• Rugalmasabb egyeztetés, üzenetek küldése és csoportok kezelése.
• Több kezelési funkció támogatott, beleértve a kapcsolatok bezárását, annak ellenőrzését, hogy létezik-e kapcsolat, felhasználó vagy csoport.
• Erősen gépelt központ
• Egyesített központ neve és kapcsolati sztring beállítása egy helyen.

Az alábbi kód bemutatja, hogyan írhat SignalR-kötéseket osztályalapú modellben:

Először is definiálja a központot egy osztályból ServerlessHub:

[SignalRConnection("AzureSignalRConnectionString")]
public class Functions : ServerlessHub
{
    private const string HubName = nameof(Functions); // Used by SignalR trigger only

    public Functions(IServiceProvider serviceProvider) : base(serviceProvider)
    {
    }

    [Function("negotiate")]
    public async Task<HttpResponseData> Negotiate([HttpTrigger(AuthorizationLevel.Anonymous, "post")] HttpRequestData req)
    {
        var negotiateResponse = await NegotiateAsync(new() { UserId = req.Headers.GetValues("userId").FirstOrDefault() });
        var response = req.CreateResponse();
        response.WriteBytes(negotiateResponse.ToArray());
        return response;
    }

    [Function("Broadcast")]
    public Task Broadcast(
    [SignalRTrigger(HubName, "messages", "broadcast", "message")] SignalRInvocationContext invocationContext, string message)
    {
        return Clients.All.SendAsync("newMessage", new NewMessage(invocationContext, message));
    }

    [Function("JoinGroup")]
    public Task JoinGroup([SignalRTrigger(HubName, "messages", "JoinGroup", "connectionId", "groupName")] SignalRInvocationContext invocationContext, string connectionId, string groupName)
    {
        return Groups.AddToGroupAsync(connectionId, groupName);
    }
}

A Program.cs fájlban regisztrálja a kiszolgáló nélküli központot:

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults(b => b.Services
        .AddServerlessHub<Functions>())
    .Build();

Tárgyalási élmény az osztályalapú modellben

A SignalR bemeneti kötés [SignalRConnectionInfoInput]használata helyett az osztályalapú modell tárgyalása rugalmasabb lehet. Az alaposztály ServerlessHub rendelkezik egy metódussal NegotiateAsync, amellyel a felhasználók testre szabhatják a tárgyalási lehetőségeket, például userId, claimsstb.

Task<BinaryData> NegotiateAsync(NegotiationOptions? options = null)

Üzenetek küldése és élmény kezelése az osztályalapú modellben

Üzeneteket küldhet, csoportokat kezelhet vagy ügyfeleket kezelhet az alaposztály ServerlessHubáltal biztosított tagok elérésével.

• ServerlessHub.Clients üzenetek ügyfeleknek való küldéséhez.
• ServerlessHub.Groups a csoportokkal való kapcsolatok kezeléséhez, például a kapcsolatok csoportokhoz való hozzáadásához, a csoportokból való kapcsolatok eltávolításához.
• ServerlessHub.UserGroups a csoportokkal rendelkező felhasználók kezeléséhez, például a felhasználók csoportokhoz való hozzáadásához, a felhasználók csoportokból való eltávolításához.
• ServerlessHub.ClientManager a kapcsolatok meglétének ellenőrzéséhez, a kapcsolatok bezárásához stb.

Erősen gépelt központ

Az erősen gépelt központ lehetővé teszi, hogy erősen gépelt metódusokat használjon, amikor üzeneteket küld az ügyfeleknek. Ha az osztályalapú modellben erősen gépelt központot szeretne használni, bontsa ki az ügyfél metódusait egy interfészbe T, és állítsa le a hubosztályt a forrásból ServerlessHub<T>.

Az alábbi kód egy felületi minta az ügyfélmetelyekhez.

public interface IChatClient
{
    Task newMessage(NewMessage message);
}

Ezután az erősen beírt metódusokat az alábbiak szerint használhatja:

[SignalRConnection("AzureSignalRConnectionString")]
public class Functions : ServerlessHub<IChatClient>
{
    private const string HubName = nameof(Functions);  // Used by SignalR trigger only

    public Functions(IServiceProvider serviceProvider) : base(serviceProvider)
    {
    }

    [Function("Broadcast")]
    public Task Broadcast(
    [SignalRTrigger(HubName, "messages", "broadcast", "message")] SignalRInvocationContext invocationContext, string message)
    {
        return Clients.All.newMessage(new NewMessage(invocationContext, message));
    }
}

Feljegyzés

Teljes projektmintát kaphat a GitHubról.

Egyesített központ neve és kapcsolati sztring beállítása egy helyen

• A kiszolgáló nélküli központ osztályneve automatikusan a következőképpen lesz használva HubName: .
• Előfordulhat, hogy a SignalRConnection kiszolgáló nélküli központi osztályokban az alábbi attribútumot észlelte:

  [SignalRConnection("AzureSignalRConnectionString")]
  public class Functions : ServerlessHub<IChatClient>
  

  Lehetővé teszi a kiszolgáló nélküli központ kapcsolati sztring testreszabását. Ha hiányzik, a rendszer az alapértelmezett értéket AzureSignalRConnectionString használja.

Fontos

A SignalR-eseményindítók és a kiszolgáló nélküli központok függetlenek. Ezért a kiszolgáló nélküli központ és SignalRConnection attribútum osztályneve nem változtatja meg a SignalR-eseményindítók beállításait, még akkor sem, ha a Kiszolgáló nélküli központban használja a SignalR-eseményindítókat.

Folyamaton belüli modell

Az osztályalapú modell konzisztens SignalR-kiszolgálóoldali programozási élményt nyújt a következő funkciókkal:

• Kevesebb konfigurációs munka: A rendszer az osztálynevet használja HubName, a metódus nevét használja Event, és a Category rendszer automatikusan a metódus neve alapján dönt.
• Nincs szükség automatikus paraméterkötésre: ParameterNames és attribútumra [SignalRParameter] . A paraméterek automatikusan az Azure-függvény metódusainak argumentumaihoz vannak kötve sorrendben.
• Kényelmes kimeneti és tárgyalási felület.

Az alábbi kód az alábbi funkciókat mutatja be:

public class HubName1 : ServerlessHub
{
    [FunctionName("negotiate")]
    public SignalRConnectionInfo Negotiate([HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req)
    {
        return Negotiate(req.Headers["x-ms-signalr-user-id"], GetClaims(req.Headers["Authorization"]));
    }

    [FunctionName(nameof(OnConnected))]
    public async Task OnConnected([SignalRTrigger]InvocationContext invocationContext, ILogger logger)
    {
        await Clients.All.SendAsync(NewConnectionTarget, new NewConnection(invocationContext.ConnectionId));
        logger.LogInformation($"{invocationContext.ConnectionId} has connected");
    }

    [FunctionName(nameof(Broadcast))]
    public async Task Broadcast([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
    {
        await Clients.All.SendAsync(NewMessageTarget, new NewMessage(invocationContext, message));
        logger.LogInformation($"{invocationContext.ConnectionId} broadcast {message}");
    }

    [FunctionName(nameof(OnDisconnected))]
    public void OnDisconnected([SignalRTrigger]InvocationContext invocationContext)
    {
    }
}

Az osztályalapú modellt használni kívánt összes függvénynek a ServerlessHubtól öröklő osztály metódusának kell lennie. A mintában szereplő osztálynév HubName1 a központi név.

Központ metódusának definiálása

Minden központi metódusnak rendelkeznie InvocationContext kell egy attribútummal dekorált argumentummal[SignalRTrigger], és paraméter nélküli konstruktort kell használnia. Ezután a metódus neve paramétereseményként lesz kezelve.

Alapértelmezés szerint a category=messages metódusnév kivételével a következő nevek egyike:

• OnConnected: Kezelt category=connections, event=connected
• OnDisconnected: Kezelt category=connections, event=disconnected

Paraméterkötési felület

Az osztályalapú modellben szükségtelen, [SignalRParameter] mert az összes argumentum alapértelmezés szerint van megjelölve [SignalRParameter] , kivéve az alábbi helyzetek egyikét:

• Az argumentumot egy kötési attribútum díszíti
• Az argumentum típusa vagy ILogger típusa CancellationToken
• Az argumentumot attribútum díszíti [SignalRIgnore]

Tárgyalási élmény az osztályalapú modellben

A SignalR bemeneti kötés [SignalR]használata helyett az osztályalapú modell tárgyalása rugalmasabb lehet. Az alaposztálynak ServerlessHub van egy metódusa:

SignalRConnectionInfo Negotiate(string userId = null, IList<Claim> claims = null, TimeSpan? lifeTime = null)

Ez a funkció lehetővé teszi a felhasználó számára a függvény végrehajtásának testreszabását userId vagy claims végrehajtását.

Használja a következő parancsot: SignalRFilterAttribute

A felhasználó örökölheti és implementálhatja az absztrakt osztályt SignalRFilterAttribute. Ha kivételek lépnek fel FilterAsync, 403 Forbidden a rendszer visszaküldi az ügyfeleknek.

Az alábbi minta bemutatja, hogyan implementálhat olyan ügyfélszűrőt, amely csak a admin meghívást broadcastteszi lehetővé.

[AttributeUsage(AttributeTargets.Method, AllowMultiple = true, Inherited = true)]
internal class FunctionAuthorizeAttribute: SignalRFilterAttribute
{
    private const string AdminKey = "admin";

    public override Task FilterAsync(InvocationContext invocationContext, CancellationToken cancellationToken)
    {
        if (invocationContext.Claims.TryGetValue(AdminKey, out var value) &&
            bool.TryParse(value, out var isAdmin) &&
            isAdmin)
        {
            return Task.CompletedTask;
        }

        throw new Exception($"{invocationContext.ConnectionId} doesn't have admin role");
    }
}

Használja az attribútumot a függvény engedélyezéséhez.

[FunctionAuthorize]
[FunctionName(nameof(Broadcast))]
public async Task Broadcast([SignalRTrigger]InvocationContext invocationContext, string message, ILogger logger)
{
}

Ügyfélfejlesztés

A SignalR-ügyfélalkalmazások a SignalR ügyféloldali SDK-t több nyelven is használhatják, így könnyen csatlakozhatnak és fogadhatnak üzeneteket az Azure SignalR Szolgáltatásból.

Ügyfélkapcsolat konfigurálása

A SignalR szolgáltatáshoz való csatlakozáshoz az ügyfélnek az alábbi lépésekből álló sikeres kapcsolati egyeztetést kell végrehajtania:

1. Kérés kérése a negotiate fent tárgyalt HTTP-végponthoz érvényes kapcsolati információk beszerzéséhez
2. Csatlakozás a SignalR szolgáltatáshoz a szolgáltatásvégpont URL-címével és a negotiate végpontról beszerzett hozzáférési jogkivonattal

A SignalR ügyféloldali SDK-k már tartalmazzák a tárgyalási kézfogás végrehajtásához szükséges logikát. Adja át a tárgyalási végpont URL-címét a szegmens nélkül negotiate az SDK-nak HubConnectionBuilder. Íme egy példa a JavaScriptben:

const connection = new signalR.HubConnectionBuilder()
  .withUrl("https://my-signalr-function-app.azurewebsites.net/api")
  .build();

Konvenció szerint az SDK automatikusan hozzáfűzi /negotiate az URL-címet, és azt használja a tárgyalás megkezdéséhez.

Feljegyzés

Ha a JavaScript/TypeScript SDK-t böngészőben használja, engedélyeznie kell a forrásközi erőforrás-megosztást (CORS) a függvényalkalmazásban.

A SignalR ügyféloldali SDK használatáról további információt a nyelv dokumentációjában talál:

• .NET Standard
• JavaScript
• Java

Üzenetek küldése ügyfélről a szolgáltatásba

Ha a SignalR-erőforráshoz konfigurálta a felsőbb réteget , bármely SignalR-ügyféllel küldhet üzeneteket egy ügyfélről az Azure Functionsbe. Íme egy példa a JavaScriptben:

connection.send("method1", "arg1", "arg2");

Azure Functions-konfiguráció

Az Azure SignalR Service-vel integrálható Azure-függvényalkalmazások bármely tipikus Azure-függvényalkalmazáshoz hasonlóan üzembe helyezhetők olyan technikákkal, mint a folyamatos üzembe helyezés, a zip-alapú üzembe helyezés és a csomagból való futtatás.

A SignalR szolgáltatás kötéseit használó alkalmazások esetében azonban van néhány speciális szempont. Ha az ügyfél böngészőben fut, a CORS-t engedélyezni kell. Ha az alkalmazás hitelesítést igényel, integrálhatja a tárgyalási végpontot az App Service-hitelesítéssel.

A CORS engedélyezése

A JavaScript/TypeScript-ügyfél HTTP-kérést küld a tárgyalási függvényhez a kapcsolat egyeztetésének kezdeményezéséhez. Ha az ügyfélalkalmazást az Azure-függvényalkalmazástól eltérő tartományban üzemeltetik, engedélyezni kell a forrásalapú erőforrás-megosztást (CORS) a függvényalkalmazásban, vagy a böngésző letiltja a kéréseket.

Localhost

Amikor a függvényalkalmazást a helyi számítógépen futtatja, hozzáadhat egy szakaszt Host a local.settings.json a CORS engedélyezéséhez. Host A szakaszban adjon hozzá két tulajdonságot:

• CORS - adja meg az ügyfélalkalmazás forrásának alap URL-címét
• CORSCredentials - állítsa be úgy, hogy engedélyezze a true "hitelesítő adatokkal" kéréseket

Példa:

{
  "IsEncrypted": false,
  "Values": {
    // values
  },
  "Host": {
    "CORS": "http://localhost:8080",
    "CORSCredentials": true
  }
}

Felhő – Azure Functions CORS

Ha engedélyezni szeretné a CORS-t egy Azure-függvényalkalmazáson, nyissa meg a CORS konfigurációs képernyőjét a függvényalkalmazás Platformfunkciók lapján az Azure Portalon.

Feljegyzés

A CORS-konfiguráció még nem érhető el az Azure Functions Linux-használati csomagjában. A CORS engedélyezéséhez használja az Azure API Managementet .

Az Access-Control-Allow-Credentials azonosítókkal rendelkező CORS-t engedélyezni kell ahhoz, hogy a SignalR-ügyfél meghívja a tárgyalási függvényt. Az engedélyezéshez jelölje be a jelölőnégyzetet.

Az Engedélyezett források szakaszban adjon hozzá egy bejegyzést a webalkalmazás kiindulási URL-címével.

Felhő – Azure API Management

Az Azure API Management egy API-átjárót biztosít, amely képességeket ad a meglévő háttérszolgáltatásokhoz. Segítségével CORS-t adhat hozzá a függvényalkalmazáshoz. Egy használatalapú tarifacsomagot és egy havi ingyenes támogatást kínál.

Az Azure-függvényalkalmazások importálásával kapcsolatos információkért tekintse meg az API Management dokumentációját. Az importálás után hozzáadhat egy bejövő szabályzatot, amely engedélyezi a CORS-t az Access-Control-Allow-Credentials támogatással.

<cors allow-credentials="true">
  <allowed-origins>
    <origin>https://azure-samples.github.io</origin>
  </allowed-origins>
  <allowed-methods>
    <method>GET</method>
    <method>POST</method>
  </allowed-methods>
  <allowed-headers>
    <header>*</header>
  </allowed-headers>
  <expose-headers>
    <header>*</header>
  </expose-headers>
</cors>

Konfigurálja a SignalR-ügyfeleket az API Management URL-cím használatára.

App Service-hitelesítés használata

Az Azure Functions beépített hitelesítést használ, amely olyan népszerű szolgáltatókat támogat, mint a Facebook, az X, a Microsoft Account, a Google és a Microsoft Entra ID. Ez a funkció integrálható a SignalRConnectionInfo kötéssel, hogy felhasználói azonosítóval hitelesített kapcsolatokat hozzon létre az Azure SignalR Szolgáltatással. Az alkalmazás az adott felhasználói azonosítóra célzott kimeneti kötéssel SignalR küldhet üzeneteket.

Az Azure Portalon, a Függvényalkalmazás Platformfunkciók lapján nyissa meg a Hitelesítési/engedélyezési beállítások ablakot. Kövesse az App Service-hitelesítés dokumentációját a hitelesítés konfigurálásához egy ön által választott identitásszolgáltatóval.

A konfigurálás után a hitelesített HTTP-kérések tartalmazzák x-ms-client-principal-name a hitelesített identitás felhasználónevét és x-ms-client-principal-id felhasználói azonosítóját tartalmazó fejléceket.

Ezeket a fejléceket a SignalRConnectionInfo kötéskonfigurációban használhatja hitelesített kapcsolatok létrehozásához. Íme egy példa a fejlécet használó C#-egyeztetési függvényre x-ms-client-principal-id .

[FunctionName("negotiate")]
public static SignalRConnectionInfo Negotiate(
    [HttpTrigger(AuthorizationLevel.Anonymous)]HttpRequest req,
    [SignalRConnectionInfo
        (HubName = "chat", UserId = "{headers.x-ms-client-principal-id}")]
        SignalRConnectionInfo connectionInfo)
{
    // connectionInfo contains an access key token with a name identifier claim set to the authenticated user
    return connectionInfo;
}

Ezután üzeneteket küldhet a felhasználónak egy SignalR-üzenet tulajdonságának beállításával UserId .

[FunctionName("SendMessage")]
public static Task SendMessage(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]object message,
    [SignalR(HubName = "chat")]IAsyncCollector<SignalRMessage> signalRMessages)
{
    return signalRMessages.AddAsync(
        new SignalRMessage
        {
            // the message will only be sent to these user IDs
            UserId = "userId1",
            Target = "newMessage",
            Arguments = new [] { message }
        });
}

További információ más nyelvekről: Azure SignalR Service-kötések az Azure Functions-hez referenciában.

Következő lépések

Ebből a cikkből megtudhatja, hogyan fejleszthet és konfigurálhat kiszolgáló nélküli SignalR Service-alkalmazásokat az Azure Functions használatával. Próbáljon meg saját maga létrehozni egy alkalmazást a SignalR szolgáltatás áttekintési oldalán található rövid útmutatók vagy oktatóanyagok egyikével.