Pemicu dan pengikatan Azure Web PubSub untuk Azure Functions

Artikel
01/12/2024

Referensi ini menjelaskan cara menangani peristiwa Web PubSub di Azure Functions.

Web PubSub adalah layanan yang dikelola Azure yang membantu pengembang dengan mudah membangun aplikasi web dengan fitur waktu nyata dan pola publish-subscribe.

Perbuatan	Jenis
Menjalankan fungsi saat pesan berasal dari layanan	Pengikatan pemicu
Ikat permintaan untuk menargetkan objek di bawah pemicu Http untuk negosiasi dan permintaan upstream	Pengikatan masukan
Minta layanan melakukan tindakan	Pengikatan output

Kode sumber | Paket | dokumentasi referensi API | Dokumentasi produk | Sampel

Menambahkan ke aplikasi Functions Anda

Bekerja dengan pemicu dan pengikatan mengharuskan Anda mereferensikan paket yang sesuai. Paket NuGet digunakan untuk pustaka kelas .NET sedangkan bundel ekstensi digunakan untuk semua jenis aplikasi lainnya.

Bahasa	Tambahkan dengan...	Keterangan
C#	Memasang paket NuGet, versi prarilis
Skrip C#, JavaScript, Python, PowerShell	Instal ekstensi secara eksplisit, Gunakan bundel ekstensi	Ekstensi Azure Tools disarankan untuk digunakan dengan Visual Studio Code.
Skrip C# (khusus online di portal Azure)	Menambahkan pengikatan	Untuk memperbarui ekstensi pengikatan yang ada tanpa harus menerbitkan ulang aplikasi fungsi Anda, lihat Perbarui ekstensi Anda.

Konsep kunci

Diagram showing the workflow of Azure Web PubSub service working with Function Apps.

(1)-(2) WebPubSubConnection pengikatan input dengan HttpTrigger untuk menghasilkan koneksi klien.

(3)-(4) WebPubSubTrigger memicu pengikatan atau WebPubSubContext input pengikatan dengan HttpTrigger untuk menangani permintaan layanan.

(5)-(6) WebPubSub keluaran yang mengikat untuk meminta layanan melakukan sesuatu.

Pengikatan pemicu

Gunakan pemicu fungsi untuk menangani permintaan dari layanan Azure Web PubSub.

WebPubSubTrigger digunakan saat Anda perlu menangani permintaan dari sisi layanan. Pola titik akhir pemicu akan seperti di bawah ini yang harus diatur di sisi layanan Web PubSub (Portal: pengaturan -> penanganan aktivitas -> Templat URL). Dalam pola titik akhir, bagian kueri code=<API_KEY>DIPERLUKAN saat Anda menggunakan Aplikasi Fungsi Azure karena alasan keamanan. Kuncinya dapat ditemukan di portal Microsoft Azure. Temukan sumber daya aplikasi fungsi Anda dan navigasikan ke Functions ->Kunci aplikasi ->Kunci sistem ->webpubsub_extension setelah Anda menyebarkan aplikasi fungsi ke Azure. Meskipun, kunci ini tidak diperlukan ketika Anda bekerja dengan fungsi lokal.

<Function_App_Url>/runtime/webhooks/webpubsub?code=<API_KEY>

Screenshot of get function system keys.

Contoh

[FunctionName("WebPubSubTrigger")]
public static void Run(
    [WebPubSubTrigger("<hub>", WebPubSubEventType.User, "message")] UserEventRequest request, ILogger log)
{
    log.LogInformation($"Request from: {request.ConnectionContext.UserId}");
    log.LogInformation($"Request message data: {request.Data}");
    log.LogInformation($"Request message dataType: {request.DataType}");
}

Pengikatan WebPubSubTrigger juga mendukung nilai pengembalian dalam sinkronisasi skenario, misalnya, sistem Connect dan peristiwa pengguna, saat server dapat memeriksa dan menolak permintaan klien, atau mengirim pesan lagsung ke pemanggil. Connect peristiwa menghormati ConnectEventResponse dan EventErrorResponse, dan peristiwa pengguna menghormati UserEventResponse dan EventErrorResponse, jenis istirahat yang tidak cocok dengan skenario saat ini diabaikan. Dan jika EventErrorResponse dikembalikan, layanan akan menghilangkan koneksi klien.

[FunctionName("WebPubSubTriggerReturnValueFunction")]
public static UserEventResponse Run(
    [WebPubSubTrigger("hub", WebPubSubEventType.User, "message")] UserEventRequest request)
{
    return request.CreateResponse(BinaryData.FromString("ack"), WebPubSubDataType.Text);
}

Contoh berikut menunjukkan fungsi JavaScript pemicu Web PubSub.

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

const wpsTrigger = trigger.generic({
    type: 'webPubSubTrigger',
    name: 'request',
    hub: '<hub>',
    eventName: 'message',
    eventType: 'user'
});

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
        context.log('Request from: ', request.connectionContext.userId);
        context.log('Request message data: ', request.data);
        context.log('Request message dataType: ', request.dataType);
    }
});

Pengikatan WebPubSubTrigger juga mendukung nilai pengembalian dalam sinkronisasi skenario, misalnya, sistem Connect dan peristiwa pengguna, saat server dapat memeriksa dan menolak permintaan klien, atau mengirim pesan lagsung ke klien permintaan. Dalam bahasa yang ditik dengan lemah JavaScript, bahasa ini dideserialisasi mengenai kunci objek. Dan EventErrorResponse memiliki prioritas tertinggi dibandingkan dengan objek istirahat, bahwa jika code ada dalam pengembalian, maka itu diurai ke EventErrorResponse dan koneksi klien dihilangkan.

app.generic('message', {
    trigger: wpsTrigger,
    handler: async (request, context) => {
          return { 
              "data": "ack",
              "dataType" : "text"
          };
    }
});

Tentukan pengikatan pemicu di function.json.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSubTrigger",
      "direction": "in",
      "name": "data",
      "hub": "<hub>",
      "eventName": "message",
      "eventType": "user"
    }
  ]
}

Tentukan fungsi di index.js.

module.exports = function (context, data) {
  context.log('Request from: ', context.bindingData.request.connectionContext.userId);
  context.log('Request message data: ', data);
  context.log('Request message dataType: ', context.bindingData.request.dataType);
}

Pengikatan WebPubSubTrigger juga mendukung nilai pengembalian dalam sinkronisasi skenario, misalnya, sistem Connect dan peristiwa pengguna, saat server dapat memeriksa dan menolak permintaan klien, atau mengirim pesan lagsung ke klien permintaan. Dalam bahasa yang ditik dengan lemah JavaScript, bahasa ini dideserialisasi mengenai kunci objek. Dan EventErrorResponse memiliki prioritas tertinggi dibandingkan dengan objek istirahat, bahwa jika code ada dalam pengembalian, maka itu diurai ke EventErrorResponse dan koneksi klien dihilangkan.

module.exports = async function (context) {
  return { 
    "data": "ack",
    "dataType" : "text"
  };
}

Atribut dan anotasi

Di pustaka kelas C#, gunakan atribut WebPubSubTrigger.

Berikut ini adalah atributWebPubSubTrigger dalam metode yang khas:

[FunctionName("WebPubSubTrigger")]
public static void Run([WebPubSubTrigger("<hub>", <WebPubSubEventType>, "<event-name>")] 
    WebPubSubConnectionContext context, ILogger log)
{
    ...
}

Untuk contoh lengkapnya, lihat contoh C#.

Konfigurasi

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda atur di file function.json.

Properti function.json	Properti atribut	Deskripsi
jenis	n/a	Wajib - harus diatur ke `webPubSubTrigger`.
arah	n/a	Wajib - harus diatur ke `in`.
nama	n/a	Diperlukan - nama variabel yang digunakan dalam kode fungsi untuk parameter yang menerima data peristiwa.
hub	Hub	Wajib - nilai harus disetel ke nama hub Web PubSub agar fungsi dapat dipicu. Kami mendukung pengaturan nilai dalam atribut sebagai prioritas yang lebih tinggi, atau dapat diatur dalam pengaturan aplikasi sebagai nilai global.
eventType	WebPubSubEventType	Wajib - nilai harus ditetapkan sebagai jenis pesan peristiwa agar fungsi dapat dipicu. Nilainya harus `user` atau `system`.
eventName	EventName	Wajib - nilai harus ditetapkan sebagai peristiwa pesan agar fungsi dapat dipicu. Untuk `system` jenis peristiwa, nama peristiwa harus dalam `connect`, , `connecteddisconnected`. Untuk subprotokola yang ditentukan pengguna, nama peristiwanya adalah `message`. Untuk subprotokola `json.webpubsub.azure.v1.`yang didukung sistem, nama peristiwa adalah nama peristiwa yang ditentukan pengguna.
koneksi	Connection	Opsional - nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan layanan Azure Web PubSub upstream. Nilai digunakan untuk validasi tanda tangan. Dan nilai diselesaikan secara otomatis dengan pengaturan aplikasi "WebPubSub Koneksi ionString" secara default. Dan `null` berarti validasi tidak diperlukan dan selalu berhasil.

Penggunaan

Di C#, WebPubSubEventRequest adalah jenis parameter pengikatan yang dikenali, parameter lainnya terikat oleh nama parameter. Periksa tabel di bawah parameter dan jenis yang tersedia.

Dalam bahasa yang ditik lemah seperti JavaScript, name di function.json digunakan untuk mengikat objek pemicu mengenai tabel pemetaan di bawah ini. Dan hormati dataTypefunction.json untuk mengonversi pesan yang sesuai ketika name diatur ke data sebagai objek pengikatan untuk input pemicu. Semua parameter dapat dibaca dari context.bindingData.<BindingName> dan dikonversi JObject .

Nama mengikat	Jenis Pengikatan Data	Deskripsi	Properti
permintaan	`WebPubSubEventRequest`	Menjelaskan permintaan upstream	Properti berbeda dengan jenis peristiwa yang berbeda, termasuk kelas turunan `ConnectEventRequest`, `ConnectedEventRequest`, `UserEventRequest`, dan `DisconnectedEventRequest`
connectionContext	`WebPubSubConnectionContext`	Informasi permintaan umum	EventType, EventName, Hub, ConnectionId, UserId, Headers, Asal, Tanda Tangan, Status
data	`BinaryData`,`string`,,`Stream`,`byte[]`	Meminta data pesan dari klien dalam peristiwa `message` pengguna	-
dataType	`WebPubSubDataType`	Meminta dataType pesan, yang mendukung `binary`, , `textjson`	-
claims	`IDictionary<string, string[]>`	Klaim Pengguna dalam permintaan sistem `connect`	-
pertanyaan	`IDictionary<string, string[]>`	Kueri pengguna dalam permintaan sistem `connect`	-
subrotokol	`IList<string>`	Subprotokol yang tersedia di permintaan sistem `connect`	-
clientCertificates	`IList<ClientCertificate>`	Daftar thumbprint sertifikat dari klien di permintaan sistem `connect`	-
reason	`string`	Alasan dalam permintaan sistem `disconnected`	-

Penting

Di C#, beberapa jenis parameter yang didukung HARUS dimasukkan ke dalam yang pertama, yaitu request atau data bahwa selain jenis default BinaryData untuk membuat pengikatan fungsi dengan benar.

Mengembalikan respons

WebPubSubTrigger menghormati respons yang dikembalikan pelanggan untuk peristiwa connect sinkron dan peristiwa pengguna. Hanya respons yang cocok yang dikirim kembali ke layanan, jika tidak, respons tersebut diabaikan. Selain itu, objek pengembalia WebPubSubTrigger mendukung pengguna ke SetState() dan ClearStates() untuk mengelola metadata untuk koneksi. Dan ekstensi menggabungkan hasil dari nilai pengembalian dengan yang asli dari permintaan WebPubSubConnectionContext.States. Nilai dalam kunci yang ada ditimpa dan nilai dalam kunci baru ditambahkan.

Jenis Hasil	Deskripsi	Properti
`ConnectEventResponse`	Tanggapan untuk `connect` acara	Grup, Peran, UserId, Subprotokol
`UserEventResponse`	Respons untuk acara pengguna	DataType, Data
`EventErrorResponse`	Respons kesalahan untuk acara sinkronisasi	Kode, ErrorMessage
`*WebPubSubEventResponse`	Jenis respons dasar dari yang didukung yang digunakan untuk kasus pengembalian yang tidak pasti	-

Pengikatan masukan

Ekstensi kami menyediakan dua pengikatan input yang menargetkan kebutuhan yang berbeda.

WebPubSubConnection

Agar klien dapat terhubung ke Layanan Azure Web PubSub, klien harus mengetahui URL titik akhir layanan dan token akses yang valid. Ikatan masukan WebPubSubConnection menghasilkan informasi yang diperlukan, sehingga klien tidak perlu menangani pembuatan token ini sendiri. Karena token dibatasi waktu dan dapat digunakan untuk mengautentikasi pengguna tertentu ke koneksi, jangan menyimpan token atau membagikannya di antara klien. Pemicu HTTP yang bekerja dengan pengikatan input ini dapat digunakan bagi klien untuk mengambil informasi koneksi.
WebPubSubContext

Saat menggunakan Aplikasi Web Statis, HttpTrigger adalah satu-satunya pemicu yang didukung dan di bawah skenario Web PubSub, kami menyediakan WebPubSubContext pengikatan input yang membantu pengguna membatalkan permintaan http upstream dari sisi layanan di bawah protokol Web PubSub. Jadi pelanggan bisa mendapatkan hasil serupa dibandingkan dengan WebPubSubTrigger untuk menangani fungsi dengan mudah. Lihat contoh di bawah. Saat digunakan dengan HttpTrigger, pelanggan perlu mengonfigurasi url terbuka HttpTrigger di penanganan aktivitas yang sesuai.

Contoh - `WebPubSubConnection`

Contoh berikut menunjukkan fungsi C# yang memperoleh informasi koneksi Web PubSub menggunakan pengikatan input dan mengembalikannya melalui HTTP. Pada contoh di bawah ini, UserId dilewatkan melalui bagian kueri permintaan klien seperti ?userid={User-A}.

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{query.userid}")] WebPubSubConnection connection)
{
    return connection;
}

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')) };
    },
});

Tentukan pengikatan input di function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    },
    {
      "type": "webPubSubConnection",
      "name": "connection",
      "userId": "{query.userid}",
      "hub": "<hub>",
      "direction": "in"
    }
  ]
}

Tentukan fungsi di index.js.

module.exports = function (context, req, connection) {
  context.res = { body: connection };
  context.done();
};

token yang diautentikasi

Jika fungsi dipicu oleh klien yang diautentikasi, Anda dapat menambahkan klaim ID pengguna ke token yang dihasilkan. Anda dapat dengan mudah menambahkan autentikasi ke aplikasi fungsi menggunakan Autentikasi App Service.

Autentikasi App Service menetapkan header HTTP bernama x-ms-client-principal-id dan x-ms-client-principal-name yang masing-masingnya berisi ID dan nama utama klien pengguna yang diautentikasi.

Anda dapat mengatur properti UserId dari pengikatan ke nilai dari salah satu header menggunakan ekspresi pengikatan: {headers.x-ms-client-principal-id} atau {headers.x-ms-client-principal-name}.

[FunctionName("WebPubSubConnectionInputBinding")]
public static WebPubSubConnection Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubConnection(Hub = "<hub>", UserId = "{headers.x-ms-client-principal-name}")] WebPubSubConnection connection)
{
    return connection;
}

Catatan

Terbatas pada jenis parameter pengikatan tidak mendukung cara untuk meneruskan daftar atau array, WebPubSubConnection tidak sepenuhnya didukung dengan semua parameter yang dimiliki SDK server, terutama roles, dan juga mencakup groups dan expiresAfter. Jika pelanggan perlu menambahkan peran atau menunda membangun token akses dalam fungsi, disarankan untuk bekerja dengan SDK server untuk C#.

[FunctionName("WebPubSubConnectionCustomRoles")]
public static async Task<Uri> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest 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);
    return await serviceClient.GetClientAccessUriAsync(TimeSpan.FromMinutes(5), userId, roles);
}

Catatan

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

Catatan

Tentukan pengikatan input di function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "res"
    }
  ]
}

Tentukan fungsi di index.js.

const { WebPubSubServiceClient } = require('@azure/web-pubsub');

module.exports = async function (context, req) {
  const serviceClient = new WebPubSubServiceClient(process.env.WebPubSubConnectionString, "<hub>");
  let token = await serviceClient.getAuthenticationToken({ userId: req.query.userid, roles: ["webpubsub.joinLeaveGroup", "webpubsub.sendToGroup"] });
  context.res = { body: token.url };
  context.done();
};

Contoh - `WebPubSubContext`

Contoh berikut menunjukkan fungsi C# yang memperoleh informasi permintaan upstream Web PubSub menggunakan pengikatan input di bawah jenis peristiwa connect dan mengembalikannya melalui HTTP.

[FunctionName("WebPubSubContextInputBinding")]
public static object Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSubContext] WebPubSubContext wpsContext)
{
    // in the case request is a preflight or invalid, directly return prebuild response by extension.
    if (wpsContext.IsPreflight || wpsContext.HasError)
    {
        return wpsContext.Response;
    }
    var request = wpsContext.Request as ConnectEventRequest;
    var response = new ConnectEventResponse
    {
        UserId = wpsContext.Request.ConnectionContext.UserId
    };
    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 };
    }
});

Tentukan pengikatan input di function.json.

{
  "disabled": false,
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": ["get", "post"]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "webPubSubContext",
      "name": "wpsContext",
      "direction": "in"
    }
  ]
}

Tentukan fungsi di index.js.

module.exports = async function (context, req, wpsContext) {
  // in the case request is a preflight or invalid, directly return prebuild response by extension.
  if (wpsContext.hasError || wpsContext.isPreflight)
  {
    return wpsContext.response;
  }
  // return an http response with connect event response as body.
  return { body: {"userId": wpsContext.connectionContext.userId} };
};

Konfigurasi

WebPubSubConnection

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda tetapkan dalam file function.json dan WebPubSubConnection atribut .

Properti function.json	Properti atribut	Deskripsi
jenis	n/a	Harus disetel ke `webPubSubConnection`
arah	n/a	Harus disetel ke `in`
nama	n/a	Nama variabel yang digunakan dalam kode fungsi untuk objek pengikatan koneksi input.
hub	Hub	Wajib - Nilai harus diatur ke nama hub Web PubSub agar fungsi dapat dipicu. Kami mendukung pengaturan nilai dalam atribut sebagai prioritas yang lebih tinggi, atau dapat diatur dalam pengaturan aplikasi sebagai nilai global.
userId	UserId	Opsional - nilai klaim pengenal pengguna ditetapkan dalam token kunci akses.
koneksi	Connection	Diperlukan - Nama pengaturan aplikasi yang berisi string koneksi Layanan Web PubSub (defaultnya adalah "WebPubSubConnectionString").

WebPubSubContext

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda tetapkan di file functions.json dan atribut WebPubSubContext.

Properti function.json	Properti atribut	Deskripsi
jenis	n/a	Harus diatur ke `webPubSubContext`.
arah	n/a	Harus diatur ke `in`.
nama	n/a	Nama variabel yang digunakan dalam kode fungsi untuk input permintaan Web PubSub.
koneksi	Connection	Opsional - nama pengaturan aplikasi atau kumpulan pengaturan yang menentukan layanan Azure Web PubSub upstream. Nilai digunakan untuk Perlindungan Penyalahgunaan dan validasi Tanda Tangan. Nilai diselesaikan secara otomatis dengan "WebPubSub Koneksi ionString" secara default. Dan `null` berarti validasi tidak diperlukan dan selalu berhasil.

Penggunaan

WebPubSubConnection

WebPubSubConnection menyediakan properti di bawah ini.

Nama mengikat	Jenis Pengikatan Data	Deskripsi
BaseUri	Uri	Uri koneksi klien Web PubSub.
Uri	Uri	Uri Absolut dari koneksi Web PubSub, berisi `AccessToken` yang dibuat berdasarkan permintaan.
AccessToken	string	Menghasilkan `AccessToken` berdasarkan permintaan UserId dan informasi layanan.

WebPubSubConnection menyediakan properti di bawah ini.

Nama mengikat	Deskripsi
baseUrl	Uri koneksi klien Web PubSub.
url	Uri Absolut dari koneksi Web PubSub, berisi `AccessToken` yang dibuat berdasarkan permintaan.
accessToken	Menghasilkan `AccessToken` berdasarkan permintaan UserId dan informasi layanan.

WebPubSubConnection menyediakan properti di bawah ini.

Nama mengikat	Deskripsi
baseUrl	Uri koneksi klien Web PubSub.
url	Uri Absolut dari koneksi Web PubSub, berisi `AccessToken` yang dibuat berdasarkan permintaan.
accessToken	Menghasilkan `AccessToken` berdasarkan permintaan UserId dan informasi layanan.

WebPubSubContext

WebPubSubContext menyediakan properti di bawah ini.

Nama mengikat	Jenis Pengikatan Data	Deskripsi	Properti
permintaan	`WebPubSubEventRequest`	Permintaan dari klien, lihat tabel di bawah ini untuk detailnya.	`WebPubSubConnectionContext` dari header permintaan dan properti lainnya yang diseralisasi dari badan permintaan menjelaskan permintaan, misalnya, `Reason` untuk `DisconnectedEventRequest`.
respons	`HttpResponseMessage`	Ekstensi membangun respons terutama untuk `AbuseProtection` dan kasus kesalahan.	-
ErrorMessage	string	Jelaskan detail kesalahan saat memproses permintaan upstream.	-
hasError	bool	Tandai dengan bendera untuk menunjukkan apakah itu permintaan upstream Web PubSub yang valid.	-
isPreflight	bool	Tandai dengan bendera untuk menunjukkan apakah itu permintaan prapenerbangan `AbuseProtection`.	-

Untuk WebPubSubEventRequest, dideserialisasikan ke kelas berbeda yang memberikan informasi berbeda tentang skenario permintaan. Untuk PreflightRequest atau kasus yang tidak valid, pengguna dapat memeriksa bendera IsPreflight dan HasError untuk mengetahuinya. Disarankan untuk mengembalikan respons build sistem WebPubSubContext.Response secara langsung, atau pelanggan dapat mencatat kesalahan sesuai permintaan. Dalam skenario yang berbeda, pelanggan dapat membaca properti permintaan seperti di bawah ini.

Kelas Turunan	Deskripsi	Properti
`PreflightRequest`	Digunakan di `AbuseProtection` bila `IsPreflight`true	-
`ConnectEventRequest`	Digunakan dalam jenis peristiwa sistem `Connect`	Klaim, Kueri, Subprotokol, Sertifikat Klien
`ConnectedEventRequest`	Digunakan dalam jenis peristiwa sistem `Connected`	-
`UserEventRequest`	Digunakan dalam jenis peristiwa pengguna	Data, DataType
`DisconnectedEventRequest`	Digunakan dalam jenis peristiwa sistem `Disconnected`	Alasan

Catatan

Meskipun WebPubSubContext merupakan pengikatan input yang memberikan cara deserialisasi cara serupa di bawah HttpTrigger dibandingkan dengan WebPubSubTrigger, ada keterbatasan, yaitu penggabungan pos status koneksi tidak didukung. Respons pengembalian masih dihormati oleh sisi layanan, tetapi pengguna harus membangun respons itu sendiri. Jika pengguna perlu mengatur respons peristiwa, Anda harus mengembalikan HttpResponseMessage berisi ConnectEventResponse atau pesan untuk peristiwa pengguna sebagai isi respons dan menempatkan status koneksi dengan kunci ce-connectionstate di header respons.

Pengikatan output

Gunakan pengikatan output Web PubSub untuk memanggil layanan Azure Web PubSub untuk melakukan sesuatu. Anda dapat menyiarkan pesan ke:

Semua klien terhubung
Klien tersambung diautentikasi ke pengguna tertentu
Klien yang terhubung bergabung dalam grup tertentu
Koneksi klien tertentu

Pengikatan output juga memungkinkan Anda untuk mengelola klien dan grup, serta memberikan/mencabut izin yang menargetkan connectionId dengan grup.

Tambahkan koneksi ke grup
Menambahkan pengguna ke grup
Hapus koneksi dari grup
Menghapus pengguna dari grup
Hapus pengguna dari semua grup
Tutup semua koneksi klien
Tutup koneksi klien tertentu
Tutup koneksi dalam grup
Berikan izin koneksi
Cabut izin koneksi

Untuk informasi tentang pengaturan dan detail konfigurasi, lihat gambaran umum.

Contoh

[FunctionName("WebPubSubOutputBinding")]
public static async Task RunAsync(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequest req,
    [WebPubSub(Hub = "<hub>")] IAsyncCollector<WebPubSubAction> actions)
{
    await actions.AddAsync(WebPubSubAction.CreateSendToAllAction("Hello Web PubSub!", WebPubSubDataType.Text));
}

const { app, output } = require('@azure/functions');
const wpsMsg = output.generic({
    type: 'webPubSub',
    name: 'actions',
    hub: '<hub>',
});

app.http('message', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [wpsMsg],
    handler: async (request, context) => {
        context.extraOutputs.set(wpsMsg, [{
            "actionName": "sendToAll",
            "data": `Hello world`,
            "dataType": `text`
        }]);
    }
});

Tentukan pengikatan di functions.json.

{
  "disabled": false,
  "bindings": [
    {
      "type": "webPubSub",
      "name": "actions",
      "hub": "<hub>",
      "direction": "out"
    }
  ]
}

Tentukan fungsi di index.js.

module.exports = async function (context) {
  context.bindings.actions = {
    "actionName": "sendToAll",
    "data": "hello",
    "dataType": "text"
  };
  context.done();
}

WebPubsubaction

WebPubSubAction adalah jenis abstrak dasar dari pengikatan keluaran. Jenis turunan mewakili server tindakan ingin layanan panggil.

Dalam bahasa C #, kami menyediakan beberapa metode statis di bawah WebPubSubAction untuk membantu menemukan tindakan yang tersedia. Misalnya, pengguna dapat membuat SendToAllAction dengan memanggil WebPubSubAction.CreateSendToAllAction().

Kelas Turunan	Properti
`SendToAllAction`	Data, DataType, Dikecualikan
`SendToGroupAction`	Grup, Data, DataType, Dikecualikan
`SendToUserAction`	UserId, Data, DataType
`SendToConnectionAction`	ConnectionId, Data, DataType
`AddUserToGroupAction`	UserId, Grup
`RemoveUserFromGroupAction`	UserId, Grup
`RemoveUserFromAllGroupsAction`	UserId
`AddConnectionToGroupAction`	ConnectionId, Grup
`RemoveConnectionFromGroupAction`	ConnectionId, Grup
`CloseAllConnectionsAction`	Dikecualikan, Alasan
`CloseClientConnectionAction`	ConnectionId, Alasan
`CloseGroupConnectionsAction`	Grup, Dikecualikan, Alasan
`GrantPermissionAction`	ConnectionId, Izin, TargetName
`RevokePermissionAction`	ConnectionId, Izin, TargetName

Dalam bahasa yang diketik lemah seperti javascript, actionName adalah parameter kunci untuk menyelesaikan jenis, tindakan yang tersedia tercantum seperti di bawah ini.

ActionName	Properti
`sendToAll`	Data, DataType, Dikecualikan
`sendToGroup`	Grup, Data, DataType, Dikecualikan
`sendToUser`	UserId, Data, DataType
`sendToConnection`	ConnectionId, Data, DataType
`addUserToGroup`	UserId, Grup
`removeUserFromGroup`	UserId, Grup
`removeUserFromAllGroups`	UserId
`addConnectionToGroup`	ConnectionId, Grup
`removeConnectionFromGroup`	ConnectionId, Grup
`closeAllConnections`	Dikecualikan, Alasan
`closeClientConnection`	ConnectionId, Alasan
`closeGroupConnections`	Grup, Dikecualikan, Alasan
`grantPermission`	ConnectionId, Izin, TargetName
`revokePermission`	ConnectionId, Izin, TargetName

Penting

Properti data pesan dalam tindakan terkait kirim pesan harus string jika jenis data diatur ke json atau text untuk menghindari ambiguitas konversi data. Silakan gunakan JSON.stringify() untuk mengonversi objek json yang dibutuhkan. Ini diterapkan ke tempat mana pun menggunakan properti pesan, misalnya, UserEventResponse.Data bekerja dengan WebPubSubTrigger.

Ketika jenis data diatur ke binary, diizinkan untuk memanfaatkan pengikatan yang didukung secara alami dataType sebagaimana binary dikonfigurasi dalam function.json, lihat Pemicu dan definisi pengikatan untuk detail.

Dalam bahasa yang diketik lemah seperti javascript, actionName adalah parameter kunci untuk menyelesaikan jenis, tindakan yang tersedia tercantum seperti di bawah ini.

ActionName	Properti
`sendToAll`	Data, DataType, Dikecualikan
`sendToGroup`	Grup, Data, DataType, Dikecualikan
`sendToUser`	UserId, Data, DataType
`sendToConnection`	ConnectionId, Data, DataType
`addUserToGroup`	UserId, Grup
`removeUserFromGroup`	UserId, Grup
`removeUserFromAllGroups`	UserId
`addConnectionToGroup`	ConnectionId, Grup
`removeConnectionFromGroup`	ConnectionId, Grup
`closeAllConnections`	Dikecualikan, Alasan
`closeClientConnection`	ConnectionId, Alasan
`closeGroupConnections`	Grup, Dikecualikan, Alasan
`grantPermission`	ConnectionId, Izin, TargetName
`revokePermission`	ConnectionId, Izin, TargetName

Penting

Konfigurasi

WebPubSub

Tabel berikut menjelaskan properti konfigurasi pengikatan yang Anda tetapkan dalam file function.json dan WebPubSub atribut .

Properti function.json	Properti atribut	Deskripsi
jenis	n/a	Harus disetel ke `webPubSub`
arah	n/a	Harus disetel ke `out`
nama	n/a	Nama variabel yang digunakan dalam kode fungsi untuk objek pengikatan keluaran.
hub	Hub	Nilai harus disetel ke nama hub Web PubSub agar fungsi dapat dipicu. Kami mendukung pengaturan nilai dalam atribut sebagai prioritas yang lebih tinggi, atau dapat diatur dalam pengaturan aplikasi sebagai nilai global.
koneksi	Connection	Nama pengaturan aplikasi yang berisi string koneksi Layanan Web PubSub (defaultnya adalah "WebPubSubConnectionString").

Pemecahan Masalah

Menyiapkan pembuatan log konsol

Anda juga dapat dengan mudah mengaktifkan pencatatan log konsol jika Anda ingin menggali lebih dalam permintaan yang Anda buat terhadap layanan tersebut.