Azure İşlevleri için Azure Web PubSub giriş bağlamaları

Uzantımız farklı gereksinimleri hedefleyen iki giriş bağlaması sağlar.

  • WebPubSubConnection

    İstemcinin Azure Web PubSub Hizmeti'ne bağlanmasına izin vermek için hizmet uç noktası URL'sini ve geçerli bir erişim belirtecini bilmesi gerekir. Giriş bağlaması WebPubSubConnection gerekli bilgileri üretir, bu nedenle istemcinin bu belirteç oluşturma işleminin kendisini işlemesi gerekmez. Belirteç zaman sınırlıdır ve belirli bir kullanıcının bağlantı kimliğini doğrulayabilir. Bu nedenle, belirteci önbelleğe alma veya istemciler arasında paylaşmayın. İstemcilerin bağlantı bilgilerini alması için bu giriş bağlamasıyla çalışan bir HTTP tetikleyicisi kullanılabilir.

  • WebPubSubContext

    Static Web Apps kullanılırken desteklenen HttpTrigger tek tetikleyicidir. Web PubSub senaryolarında, giriş bağlaması WebPubSubContext kullanıcıların Web PubSub protokolleri altında hizmetten gelen yukarı akış HTTP isteklerini seri durumdan çıkarmalarına yardımcı olur. Böylece müşteriler, işlevlerde kolayca işlenmek üzere WebPubSubTrigger benzer sonuçlar elde edebilir. ile HttpTriggerkullanıldığında, müşterinin olay işleyicisinde httpTrigger tarafından kullanıma sunulan URL'yi uygun şekilde yapılandırması gerekir.

WebPubSubConnection

Örnek

Aşağıdaki örnekte, giriş bağlamasını kullanarak Web PubSub bağlantı bilgilerini alan ve HTTP üzerinden döndüren bir HTTP tetikleyici işlevi gösterilmektedir. Aşağıdaki örnekte, UserId gibi ?userid={User-A}istemci isteği sorgu bölümü aracılığıyla geçirilir.

[Function("WebPubSubConnectionInputBinding")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[WebPubSubConnectionInput(Hub = "<hub>", , UserId = "{query.userid}", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
{
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteAsJsonAsync(connectionInfo);
    return response;
}

const { app, input } = require('@azure/functions');

const connection = input.generic({
    type: 'webPubSubConnection',
    name: 'connection',
    userId: '{query.userId}',
    hub: '<hub>'
});

app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [connection],
    handler: async (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get('connection')) };
    },
});

Klasör anlaşması oluşturun ve negotiate/function.json güncelleştirin ve aşağıdaki JSON kodlarını kopyalayın.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{query.userid}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

negotiate/init.py içinde işlevi tanımlayın.

import logging

import azure.functions as func

def main(req: func.HttpRequest, connection) -> func.HttpResponse:
    return func.HttpResponse(connection)

Not

Bu dil için tam örnekler beklemede

Not

Java için Web PubSub uzantıları henüz desteklenmemektedir.

Kimliği doğrulanmış kullanıcı kimliğini alma

İşlev kimliği doğrulanmış bir istemci tarafından tetikleniyorsa, oluşturulan belirteçe bir kullanıcı kimliği talebi ekleyebilirsiniz. App Service Kimlik Doğrulamasını kullanarak işlev uygulamasına kolayca kimlik doğrulaması ekleyebilirsiniz.

App Service Kimlik Doğrulaması, kimliği doğrulanmış kullanıcının istemci asıl kimliğini ve adını içeren ve adlı x-ms-client-principal-idx-ms-client-principal-name HTTP üst bilgilerini ayarlar.

Bağlama özelliğini bir bağlama ifadesi kullanarak üst bilgiden değere ayarlayabilirsiniz UserId : {headers.x-ms-client-principal-id} veya {headers.x-ms-client-principal-name}.

[Function("WebPubSubConnectionInputBinding")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req,
[WebPubSubConnectionInput(Hub = "<hub>", , UserId = "{headers.x-ms-client-principal-id}", Connection = "<web_pubsub_connection_name>")] WebPubSubConnection connectionInfo)
{
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteAsJsonAsync(connectionInfo);
    return response;
}

const { app, input } = require('@azure/functions');

const connection = input.generic({
    type: 'webPubSubConnection',
    name: 'connection',
    userId: '{headers.x-ms-client-principal-id}',
    hub: '<hub>'
});

app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [connection],
    handler: async (request, context) => {
        return { body: JSON.stringify(context.extraInputs.get('connection')) };
    },
});

Klasör anlaşması oluşturun ve negotiate/function.json güncelleştirin ve aşağıdaki JSON kodlarını kopyalayın.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{headers.x-ms-client-principal-id}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

negotiate/init.py içinde işlevi tanımlayın.

import logging

import azure.functions as func

def main(req: func.HttpRequest, connection) -> func.HttpResponse:
    return func.HttpResponse(connection)

Not

Bu dil için tam örnekler beklemede

Not

Java için Web PubSub uzantıları henüz desteklenmemektedir.

Yapılandırma

Aşağıdaki tabloda, function.json dosyasında ve WebPubSubConnection özniteliğinde ayarladığınız bağlama yapılandırma özellikleri açıklanmaktadır.

function.json özelliği Öznitelik özelliği Açıklama
türü yok Şu şekilde ayarlanmalıdır: webPubSubConnection
yön yok Şu şekilde ayarlanmalıdır: in
ad yok Giriş bağlantısı bağlama nesnesi için işlev kodunda kullanılan değişken adı.
göbek Merkez Gerekli - değerin, işlevin tetiklenebilmesi için Web PubSub hub'ının adına ayarlanması gerekir. özniteliğindeki değeri daha yüksek öncelik olarak ayarlamayı destekliyoruz veya uygulama ayarlarında genel değer olarak ayarlanabilir.
userId Kullanıcı Kimliği İsteğe bağlı - erişim anahtarı belirtecinde ayarlanacak kullanıcı tanımlayıcısının değeri.
clientProtocol ClientProtocol İsteğe bağlı - İstemci protokol türü. Geçerli değerler ve değerlerini içerir defaultmqtt.
MQTT istemcileri için olarak mqttayarlamanız gerekir.
Diğer istemciler için özelliğini atlayabilir veya olarak defaultayarlayabilirsiniz.
bağlantı Bağlantı Gerekli - Web PubSub Hizmeti bağlantı dizesi içeren uygulama ayarının adı ("WebPubSubConnectionString" olarak varsayılandır).

Kullanım

WebPubSubConnection aşağıdaki özellikleri sağlar.

Bağlama Adı Bağlama Türü Açıklama
BaseUri Urı Web PubSub istemci bağlantı uri'si.
Urı Urı Web PubSub bağlantısının Mutlak Uri'si, istekte oluşturulan temeli içerir AccessToken .
AccessToken Dize İstek UserId ve hizmet bilgilerine göre oluşturulur AccessToken .

WebPubSubConnection aşağıdaki özellikleri sağlar.

Bağlama Adı Açıklama
temel URL Web PubSub istemci bağlantı uri'si.
URL Web PubSub bağlantısının Mutlak Uri'si, istekte oluşturulan temeli içerir AccessToken .
accessToken İstek UserId ve hizmet bilgilerine göre oluşturulur AccessToken .

Not

Java için Web PubSub uzantıları henüz desteklenmemektedir.

Oluşturulan belirtecin daha fazla özelleştirmesi

Bağlama parametre türleriyle sınırlı olmak üzere, liste veya dizi geçirmenin bir yolunu desteklemez, WebPubSubConnection sunucu SDK'sının sahip olduğu tüm parametrelerle tam olarak desteklenmez, özellikle rolesve groupsexpiresAfteriçerir.

Müşterinin işlevde erişim belirtecini oluşturmada rol eklemesi veya gecikmesi gerektiğinde, C# için sunucu SDK'sı ile çalışmanızı öneririz.

[Function("WebPubSubConnectionCustomRoles")]
public static HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequestData req)
{
    var serviceClient = new WebPubSubServiceClient(new Uri(endpoint), "<hub>", "<web-pubsub-connection-string>");
    var userId = req.Query["userid"].FirstOrDefault();
    // your method to get custom roles.
    var roles = GetRoles(userId);
    var url = await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
    var response = req.CreateResponse(HttpStatusCode.OK);
    response.WriteString(url.ToString());
    return response;
}

Müşterinin işlevde rol eklemesi veya erişim belirtecini oluşturma işlemini geciktirmesi gerektiğinde JavaScript için sunucu SDK'sı ile çalışmanızı öneririz.

const { app } = require('@azure/functions');
const { WebPubSubServiceClient } = require('@azure/web-pubsub');
app.http('negotiate', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    handler: async (request, context) => {
        const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");
        let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
        return { body: token.url };
    },
});

Not

Bu dil için tam örnekler beklemede

Not

Java için Web PubSub uzantıları henüz desteklenmemektedir.

WebPubSubContext

Örnek

// validate method when upstream set as http://<func-host>/api/{event}
[Function("validate")]
public static HttpResponseData Validate(
    [HttpTrigger(AuthorizationLevel.Anonymous, "options")] HttpRequestData req,
    [WebPubSubContextInput] WebPubSubContext wpsReq)
{
    return BuildHttpResponseData(req, wpsReq.Response);
}

// Respond AbuseProtection to put header correctly.
private static HttpResponseData BuildHttpResponseData(HttpRequestData request, SimpleResponse wpsResponse)
{
    var response = request.CreateResponse();
    response.StatusCode = (HttpStatusCode)wpsResponse.Status;
    response.Body = response.Body;
    foreach (var header in wpsResponse.Headers)
    {
        response.Headers.Add(header.Key, header.Value);
    }
    return response;
}

const { app, input } = require('@azure/functions');

const wpsContext = input.generic({
    type: 'webPubSubContext',
    name: 'wpsContext'
});

app.http('connect', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [wpsContext],
    handler: async (request, context) => {
        var wpsRequest = context.extraInputs.get('wpsContext');

        return { "userId": wpsRequest.request.connectionContext.userId };
    }
});

Not

Bu dil için tam örnekler beklemede

Not

Java için Web PubSub uzantıları henüz desteklenmemektedir.

Yapılandırma

Aşağıdaki tabloda, functions.json dosyasında ve WebPubSubContext özniteliğinde ayarladığınız bağlama yapılandırma özellikleri açıklanmaktadır.

function.json özelliği Öznitelik özelliği Açıklama
türü yok olarak ayarlanmalıdır webPubSubContext.
yön yok olarak ayarlanmalıdır in.
ad yok Web PubSub isteği girişi için işlev kodunda kullanılan değişken adı.
connections Bağlantılar İsteğe bağlı - Yukarı akış Azure Web PubSub hizmet bağlantılarını tanımlayan uygulama ayar adları veya ayar koleksiyonu ön ekleri dizisi. Bu değerler kötüye kullanım koruması ve imza doğrulaması için kullanılır. Belirtilmediğinde, genel WebPubSubConnectionString uygulama ayarına geri döner. Hiçbiri yapılandırılmadığında doğrulama atlanır ve tüm istekler kabul edilir.
Örnek: ["CustomWebPubSubConnection1", "CustomWebPubSubConnection2"]

Önemli

En iyi güvenlik için, işlev uygulamanız paylaşılan gizli anahtar içeren bir bağlantı dizesi kullanmak yerine Web PubSub hizmetine bağlanırken yönetilen kimlikleri kullanmalıdır. Daha fazla bilgi için bkz . Microsoft Entra Id kullanarak yönetilen kimlik isteğini yetkilendirme.

Kullanım

WebPubSubContext aşağıdaki özellikleri sağlar.

Bağlama Adı Bağlama Türü Açıklama Özellikler
istek WebPubSubEventRequest İstemciden istek, ayrıntılar için aşağıdaki tabloya bakın. WebPubSubConnectionContext istek üst bilgisinden ve istek gövdesinden seri durumdan çıkarılmış diğer özelliklerden gelen istek, örneğin için ReasonDisconnectedEventRequestisteği açıklar.
yanıt HttpResponseMessage Uzantı, çoğunlukla ve hataları için AbuseProtection yanıt oluşturur. -
hata mesajı Dize Yukarı akış isteğini işlerken hata ayrıntılarını açıklayın. -
hasError ikili Geçerli bir Web PubSub yukarı akış isteği olup olmadığını gösteren bayrak. -
isPreflight ikili Bunun bir denetim öncesi isteği AbuseProtectionolup olmadığını gösteren bayrak. -

için WebPubSubEventRequest, istek senaryosu hakkında farklı bilgiler sağlayan farklı sınıflara seri durumdan çıkarılır. Geçerli veya geçerli olmayan durumlar için PreflightRequest kullanıcı bayrakları IsPreflight denetleyebilir ve HasError bunu bilebilir. Sistem derleme yanıtlarını WebPubSubContext.Response doğrudan döndürmenizi öneririz veya müşteri isteğe bağlı olarak hataları günlüğe kaydedebilir. Farklı senaryolarda müşteri istek özelliklerini aşağıdaki gibi okuyabilir.

Türetilmiş Sınıf Açıklama Özellikler
PreflightRequest True olduğunda AbuseProtectioniçinde IsPreflight kullanılır -
ConnectEventRequest Sistem Connect olay türünde kullanılır Talepler, Sorgu, AltProtocols, ClientCertificates
ConnectedEventRequest Sistem Connected olay türünde kullanılır -
UserEventRequest Kullanıcı olay türünde kullanılır Veri, VeriTürü
DisconnectedEventRequest Sistem Disconnected olay türünde kullanılır Nedeni

Not

WebPubSubContext bir giriş bağlaması, ile karşılaştırılırken HttpTriggerWebPubSubTriggerbenzer bir istek seri durumdan çıkarma yöntemi sağlasa da, bazı sınırlamalar vardır; örneğin birleştirme sonrası bağlantı durumu desteklenmez. Dönüş yanıtına hizmet tarafında hala uyulsa da, kullanıcıların yanıtı kendilerinin oluşturması gerekir. Kullanıcıların olay yanıtını ayarlaması gerekiyorsa, yanıt gövdesi olarak kullanıcı olayı için bir HttpResponseMessage içerir ConnectEventResponse veya iletileri döndürmeniz ve yanıt üst bilgisine anahtarla ce-connectionstate bağlantı durumu koymanız gerekir.

  • Last updated on