Azure SignalR Hizmeti ile Azure İşlevleri geliştirme ve yapılandırma

Azure İşlevleri uygulamalar, gerçek zamanlı özellikler eklemek için Azure SignalR Hizmeti bağlamalarını kullanabilir. İstemci uygulamaları, Azure SignalR Hizmeti bağlanmak ve gerçek zamanlı iletiler almak için çeşitli dillerde kullanılabilen istemci SDK'larını kullanır.

Bu makalede, SignalR Hizmeti ile tümleştirilmiş bir Azure İşlevi uygulaması geliştirme ve yapılandırma kavramları açıklanmaktadır.

SignalR Hizmeti yapılandırması

Azure SignalR Hizmeti farklı modlarda yapılandırılabilir. Azure İşlevleri ile kullanıldığında hizmetin Sunucusuz modda yapılandırılması gerekir.

Azure portalında SignalR Hizmeti kaynağınızın Ayarlar sayfasını bulun. Hizmet modunu Sunucusuz olarak ayarlayın.

Azure İşlevleri geliştirme

Azure İşlevleri ve Azure SignalR Hizmeti ile oluşturulan sunucusuz gerçek zamanlı bir uygulama için en az iki Azure İşlevleri gerekir:

• negotiate İstemcinin geçerli bir SignalR Hizmeti erişim belirteci ve uç nokta URL'si almak için çağıran bir işlev.
• SignalR Hizmeti istemcilere gönderilen iletileri işleyen bir veya daha fazla işlev.

Anlaşma işlevi

İstemci uygulaması, Azure SignalR Hizmeti bağlanmak için geçerli bir erişim belirteci gerektirir. Erişim belirteci anonim olabilir veya kullanıcı kimliğinde kimlik doğrulaması yapılabilir. Sunucusuz SignalR Hizmeti uygulamaları, belirteci ve SignalR Hizmeti uç nokta URL'si gibi diğer bağlantı bilgilerini almak için adlı negotiate bir HTTP uç noktası gerektirir.

Bağlantı bilgileri nesnesini oluşturmak için HTTP ile tetiklenen bir Azure İşlevi ve SignalRConnectionInfo giriş bağlaması kullanın. İşlevin ile biten /negotiatebir HTTP yolu olmalıdır.

C# dilinde sınıf tabanlı model ile giriş bağlamaya SignalRConnectionInfo ihtiyacınız yoktur ve özel talepleri çok daha kolay bir şekilde ekleyebilirsiniz. Daha fazla bilgi için bkz . Sınıf tabanlı modelde anlaşma deneyimi.

İşlev hakkında negotiate daha fazla bilgi için bkz. geliştirme Azure İşlevleri.

Kimliği doğrulanmış belirteç oluşturmayı öğrenmek için Bkz. App Service Kimlik Doğrulamasını Kullanma.

SignalR Hizmeti'dan gönderilen iletileri işleme

SignalR Hizmeti gönderilen iletileri işlemek için bağlamayı SignalRTrigger kullanın. İstemciler ileti gönderdiğinde veya istemciler bağlandığında veya bağlantısı kesildiğinde bildirim alabilirsiniz.

Daha fazla bilgi için bkz. SignalR Hizmeti tetikleyici bağlama başvurusu.

Ayrıca, bir istemciden ileti geldiğinde hizmetin işlevi tetiklemesi için işlev uç noktanızı yukarı akış uç noktası olarak yapılandırmanız gerekir. Yukarı akış uç noktalarını yapılandırma hakkında daha fazla bilgi için bkz . Yukarı akış uç noktaları.

Not

SignalR Hizmeti sunucusuz modda bir istemciden gelen iletiyi desteklemezStreamInvocation.

İleti gönderme ve grup üyeliğini yönetme

SignalR Azure SignalR Hizmeti bağlı istemcilere ileti göndermek için çıkış bağlamasını kullanın. İletileri tüm istemcilere yayınlayabilir veya istemcilerin bir alt kümesine gönderebilirsiniz. Örneğin, yalnızca belirli bir kullanıcı kimliğiyle kimliği doğrulanmış istemcilere veya yalnızca belirli bir gruba ileti gönderin.

Kullanıcılar bir veya daha fazla gruba eklenebilir. Çıkış bağlamasını SignalR kullanarak gruplara kullanıcı ekleyebilir veya gruplardan kullanıcı kaldırabilirsiniz.

Daha fazla bilgi için çıkış bağlama başvurusuna SignalRbakın.

SignalR Hubs

SignalR'nin hub kavramı vardır. Her istemci bağlantısının ve Azure İşlevleri gönderilen her iletinin kapsamı belirli bir hub'a göre belirlenmiştir. Bağlantılarınızı ve iletilerinizi mantıksal ad alanlarına ayırmak için hub'ları kullanabilirsiniz.

Sınıf tabanlı model

Sınıf tabanlı model C# için ayrılmıştır.

Yalıtılmış çalışan modeli

Sınıf tabanlı model, SignalR giriş ve çıkış bağlamalarını aşağıdaki özelliklerle değiştirebilen daha iyi programlama deneyimi sağlar:

• Daha esnek anlaşma, ileti gönderme ve grup yönetimi deneyimi.
• Bağlantıları kapatma, bağlantı, kullanıcı veya grubun mevcut olup olmadığını denetleme gibi daha fazla yönetim işlevi desteklenir.
• Kesin türemiş hub
• Birleşik hub adı ve bağlantı dizesi ayarı tek bir yerde.

Aşağıdaki kod, sınıf tabanlı modelde SignalR bağlamalarının nasıl yaz yapılacağını gösterir:

İlk olarak, bir sınıfından ServerlessHubtüretilen hub'ınızı tanımlayın:

[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);
    }
}

Program.cs dosyasında sunucusuz hub'ınızı kaydedin:

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

Sınıf tabanlı modelde anlaşma deneyimi

SignalR giriş bağlaması [SignalRConnectionInfoInput]kullanmak yerine, sınıf tabanlı modelde anlaşma daha esnek olabilir. Temel sınıfServerlessHub, kullanıcıların , claimsvb. gibi userIdanlaşma seçeneklerini özelleştirmesine olanak tanıyan bir yöntemine NegotiateAsyncsahiptir.

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

Sınıf tabanlı modelde ileti gönderme ve deneyimi yönetme

temel sınıfı ServerlessHubtarafından sağlanan üyelere erişerek ileti gönderebilir, grupları yönetebilir veya istemcileri yönetebilirsiniz.

• ServerlessHub.Clients istemcilerine ileti göndermek için.
• ServerlessHub.Groups gruplara bağlantı ekleme, gruplardan bağlantıları kaldırma gibi gruplarla bağlantıları yönetmek için.
• ServerlessHub.UserGroups kullanıcıları gruplara ekleme, gruplardan kullanıcı kaldırma gibi gruplarla kullanıcıları yönetmek için.
• ServerlessHub.ClientManager bağlantıların var olup olmadığını denetlemek, bağlantıları kapatmak vb. için.

Kesin türemiş Hub

Kesin türemiş hub , istemcilere ileti gönderirken kesin olarak yazılan yöntemleri kullanmanıza olanak tanır. Sınıf tabanlı modelde kesin olarak yazılan hub'ı kullanmak için, istemci yöntemlerini bir arabirime Tayıklayın ve hub sınıfınızı öğesinden ServerlessHub<T>türetilmiş yapın.

Aşağıdaki kod, istemci yöntemleri için bir arabirim örneğidir.

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

Ardından, kesin olarak yazılan yöntemleri aşağıdaki gibi kullanabilirsiniz:

[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));
    }
}

Not

GitHub'dan eksiksiz bir proje örneği alabilirsiniz.

Birleşik hub adı ve bağlantı dizesi ayarı tek bir yerde

• Sunucusuz hub'ın sınıf adı otomatik olarak olarak HubNamekullanılır.
• Sunucusuz hub sınıflarında kullanılan özniteliği aşağıdaki gibi fark SignalRConnection etmiş olabilirsiniz:

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

  Sunucusuz hub için bağlantı dizesi nerede olduğunu özelleştirmenizi sağlar. Yoksa, varsayılan değer AzureSignalRConnectionString kullanılır.

Önemli

SignalR tetikleyicileri ve sunucusuz hub'lar bağımsızdır. Bu nedenle, sunucusuz hub'ın ve SignalRConnection özniteliğin sınıf adı, sunucusuz hub içinde SignalR tetikleyicileri kullanmanıza rağmen SignalR tetikleyicilerinin ayarlarını değiştirmez.

İşlem içi model

Sınıf tabanlı model, aşağıdaki özelliklerle tutarlı bir SignalR sunucu tarafı programlama deneyimi sağlar:

• Daha az yapılandırma çalışması: Sınıf adı olarak HubNamekullanılır, yöntem adı olarak Eventkullanılır ve Category yöntem adına göre otomatik olarak belirlenir.
• Otomatik parametre bağlaması: ParameterNames ve özniteliği [SignalRParameter] gerekli değildir. Parametreler, sırasıyla Azure İşlevi yöntemlerinin bağımsız değişkenlerine otomatik olarak bağlanır.
• Kullanışlı çıkış ve anlaşma deneyimi.

Aşağıdaki kod bu özellikleri gösterir:

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)
    {
    }
}

Sınıf tabanlı modeli kullanmak isteyen tüm işlevlerin ServerlessHub'dan devralan sınıfın bir yöntemi olması gerekir. Örnekteki sınıf adı HubName1 hub adıdır.

Hub yöntemini tanımlama

Tüm hub yöntemlerinin özniteliğine InvocationContext göre [SignalRTrigger] düzenlenmiş bağımsız değişkeni olmalıdır ve parametresiz bir oluşturucu kullanmalıdır. Ardından yöntem adı parametre olayı olarak değerlendirilir.

Varsayılan olarak, category=messages yöntem adı aşağıdaki adlardan biri dışında:

• OnConnected: Olarak ele alındı category=connections, event=connected
• OnDisconnected: Olarak ele alındı category=connections, event=disconnected

Parametre bağlama deneyimi

Sınıf tabanlı modelde, [SignalRParameter] aşağıdaki durumlardan biri dışında tüm bağımsız değişkenler varsayılan olarak [SignalRParameter] işaretlendiğinden gereksizdir:

• Bağımsız değişken bir bağlama özniteliğiyle dekore edilmiştir
• Bağımsız değişkenin türü ILogger veya CancellationToken
• Bağımsız değişken özniteliğine göre düzenlenmiştir [SignalRIgnore]

Sınıf tabanlı modelde anlaşma deneyimi

SignalR giriş bağlaması [SignalR]kullanmak yerine, sınıf tabanlı modelde anlaşma daha esnek olabilir. Temel sınıfın ServerlessHub bir yöntemi vardır:

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

Bu özellik, kullanıcının işlev yürütmesi sırasında veya claims özelleştirmesine userId olanak tanır.

SignalRFilterAttribute komutunu kullanma

Kullanıcı soyut sınıfını SignalRFilterAttributedevralabilir ve uygulayabilir. içinde FilterAsync403 Forbidden özel durumlar oluşursa istemcilere geri gönderilir.

Aşağıdaki örnek, yalnızca çağrısına broadcastizin veren bir müşteri filtresinin admin nasıl uygulandığını gösterir.

[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");
    }
}

İşlevi yetkilendirmek için özniteliğini kullanın.

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

İstemci geliştirme

SignalR istemci uygulamaları, Azure SignalR Hizmeti'a kolayca bağlanmak ve ileti almak için birkaç dilden birinde SignalR istemci SDK'sını kullanabilir.

İstemci bağlantısını yapılandırma

SignalR Hizmeti bağlanmak için istemcinin şu adımlardan oluşan başarılı bir bağlantı anlaşması tamamlaması gerekir:

1. Geçerli bağlantı bilgilerini almak için negotiate yukarıda açıklanan HTTP uç noktasına bir istekte bulunın
2. Hizmet uç noktası URL'sini ve uç noktadan alınan erişim belirtecini kullanarak SignalR Hizmeti Bağlan negotiate

SignalR istemci SDK'ları, anlaşma el sıkışmasını gerçekleştirmek için gereken mantığı zaten içerir. Anlaşma uç noktasının URL'sini ( segment hariç negotiate ) SDK'nın HubConnectionBuilderöğesine geçirin. JavaScript'te bir örnek aşağıda verilmişti:

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

Kural gereği SDK, URL'ye otomatik olarak eklenir /negotiate ve anlaşma başlatmak için bunu kullanır.

Not

Tarayıcıda JavaScript/TypeScript SDK'sını kullanıyorsanız, İşlev Uygulamanızda çıkış noktaları arası kaynak paylaşımını (CORS) etkinleştirmeniz gerekir.

SignalR istemci SDK'sını kullanma hakkında daha fazla bilgi için dilinizin belgelerine bakın:

• .NET Standard
• JavaScript
• Java

İstemciden hizmete ileti gönderme

SignalR kaynağınız için yukarı akış yapılandırdıysanız, herhangi bir SignalR istemcisini kullanarak bir istemciden Azure İşlevleri ileti gönderebilirsiniz. JavaScript'te bir örnek aşağıda verilmişti:

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

Azure İşlevleri yapılandırması

Azure SignalR Hizmeti ile tümleşen Azure İşlevi uygulamaları, sürekli dağıtım, zip dağıtımı ve paketten çalıştırma gibi teknikler kullanılarak herhangi bir tipik Azure İşlevi uygulaması gibi dağıtılabilir.

Ancak, SignalR Hizmeti bağlamalarını kullanan uygulamalar için dikkat edilmesi gereken bazı özel noktalar vardır. İstemci bir tarayıcıda çalışıyorsa CORS'nin etkinleştirilmesi gerekir. Uygulama kimlik doğrulaması gerektiriyorsa, anlaşma uç noktasını App Service Kimlik Doğrulaması ile tümleştirebilirsiniz.

CORS'yi etkinleştirme

JavaScript/TypeScript istemcisi bağlantı anlaşması başlatmak için anlaşma işlevine HTTP isteğinde bulunur. İstemci uygulaması Azure İşlev uygulamasından farklı bir etki alanında barındırıldığında, işlev uygulamasında çıkış noktaları arası kaynak paylaşımı (CORS) etkinleştirilmelidir, aksi takdirde tarayıcı istekleri engeller.

Localhost

İşlev uygulamasını yerel bilgisayarınızda çalıştırırken, CORS'yi etkinleştirmek için local.settings.json bir Host bölüm ekleyebilirsiniz. Host bölümünde iki özellik ekleyin:

• CORS - İstemci uygulamasının kaynağı olan temel URL'yi girin
• CORSCredentials - "withCredentials" isteklerine izin verecek şekilde true ayarlayın

Örnek:

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

Bulut - Azure İşlevleri CORS

Azure İşlevi uygulamasında CORS'yi etkinleştirmek için Azure portalında İşlev uygulamanızın Platform özellikleri sekmesinin altındaki CORS yapılandırma ekranına gidin.

Not

CORS yapılandırması henüz Azure İşlevleri Linux Tüketim planında kullanılamaz. CORS'yi etkinleştirmek için Azure API Management'ı kullanın.

SignalR istemcisinin anlaşma işlevini çağırması için Access-Control-Allow-Credentials ile CORS etkinleştirilmelidir. Etkinleştirmek için onay kutusunu seçin.

İzin verilen çıkış noktaları bölümünde, web uygulamanızın kaynak tabanı URL'sini içeren bir giriş ekleyin.

Bulut - Azure API Management

Azure API Management, mevcut arka uç hizmetlerine özellikler ekleyen bir API ağ geçidi sağlar. İşlev uygulamanıza CORS eklemek için bunu kullanabilirsiniz. Eylem başına ödeme fiyatlandırması ve aylık ücretsiz hibe ile bir tüketim katmanı sunar.

Azure İşlevi uygulamasını içeri aktarma hakkında bilgi için API Management belgelerine bakın. İçeri aktarıldıktan sonra, Access-Control-Allow-Credentials desteğiyle CORS'yi etkinleştirmek için bir gelen ilkesi ekleyebilirsiniz.

<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>

SignalR istemcilerinizi API Management URL'sini kullanacak şekilde yapılandırın.

App Service Kimlik Doğrulamayı Kullanma

Azure İşlevleri, Facebook, Twitter, Microsoft Hesabı, Google ve Microsoft Entra Id gibi popüler sağlayıcıları destekleyen yerleşik kimlik doğrulamasına sahiptir. Bu özellik, bir kullanıcı kimliğine SignalRConnectionInfo doğrulanmış Azure SignalR Hizmeti bağlantıları oluşturmak için bağlama ile tümleştirilebilir. Uygulamanız, bu kullanıcı kimliğini hedefleyen çıkış bağlamasını SignalR kullanarak ileti gönderebilir.

Azure portalında, İşlev uygulamanızın Platform özellikleri sekmesinde Kimlik Doğrulama/yetkilendirme ayarları penceresini açın. Seçtiğiniz bir kimlik sağlayıcısını kullanarak kimlik doğrulamasını yapılandırmak için App Service Kimlik Doğrulaması belgelerini izleyin.

Yapılandırıldıktan sonra, kimliği doğrulanmış HTTP istekleri sırasıyla kimliği doğrulanmış kimliğin kullanıcı adını ve kullanıcı kimliğini içeren üst bilgileri içerir x-ms-client-principal-namex-ms-client-principal-id .

Bu üst bilgileri bağlama yapılandırmanızda SignalRConnectionInfo kullanarak kimliği doğrulanmış bağlantılar oluşturabilirsiniz. Aşağıda üst bilgiyi kullanan örnek bir C# anlaşma işlevi verilmiştir 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;
}

Ardından SignalR iletisinin UserId özelliğini ayarlayarak bu kullanıcıya ileti gönderebilirsiniz.

[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 }
        });
}

Diğer diller hakkında bilgi için bkz. Azure İşlevleri başvurusu için Azure SignalR Hizmeti bağlamaları.

Sonraki adımlar

Bu makalede, Azure İşlevleri kullanarak sunucusuz SignalR Hizmeti uygulamaları geliştirmeyi ve yapılandırmayı öğreneceksiniz. SignalR Hizmeti genel bakış sayfasındaki hızlı başlangıçlardan veya öğreticilerden birini kullanarak kendiniz uygulama oluşturmayı deneyin.