適用於 Azure Functions 的 Azure Web PubSub 觸發程序與繫結

此參考說明如何在 Azure Functions 中處理 Web PubSub 事件。

Web PubSub 是一項 Azure 受控服務，可協助開發人員輕鬆建置具有即時功能和發佈/訂閱模式的 Web 應用程式。

動作	類型
當服務發出訊息時，執行函式	觸發程序繫結
將要求繫結至 Http 觸發程序下的目標物件，以進行交涉和上游要求	輸入繫結
叫用服務執行動作	輸出繫結

原始程式碼 | 套件 | API 參考文件 | 產品文件 | 範例

新增至您的 Functions 應用程式

您需要參考適當的套件，才能使用觸發程序和繫結。 NuGet 套件用於 .NET 類別庫，而延伸模組組合則用於所有其他應用程式類型。

語言	新增者...	備註
C#	安裝 NuGet 套件 (版本發行前版本)
C# 指令碼、JavaScript、Python、PowerShell	明確安裝延伸模組，使用延伸模組套件組合	建議使用 Azure Tools 延伸模組搭配 Visual Studio Code。
C# 指令碼 (僅限 Azure 入口網站線上使用)	新增繫結	若要更新現有的繫結延伸模組，而不需重新發行您的函式應用程式，請參閱更新您的延伸模組。

重要概念

(1)-(2) WebPubSubConnection 輸入與 HttpTrigger 繫結，以產生用戶端連線。

(3)-(4) WebPubSubTrigger 觸發程序繫結，或 WebPubSubContext 輸入與 HttpTrigger 繫結，以處理服務要求。

(5)-(6) WebPubSub 輸出繫結，以要求服務執行某些動作。

觸發程序繫結

使用函式觸發程序處理來自 Azure Web PubSub 服務的要求。

當您需要處理來自服務端的要求時，會使用 WebPubSubTrigger。 觸發程序端點模式如下所示，此模式應該在 Web PubSub 服務端中設定 (入口網站：設定 -> 事件處理常式 -> URL 範本)。 在端點模式中，當您基於安全性考量使用 Azure Function 應用程式時，需要使用查詢組件 code=<API_KEY>。 可以在 Azure 入口網站中找到該金鑰。 尋找函式應用程式資源，並在將函式應用程式部署至 Azure 之後，瀏覽至函式 ->應用程式金鑰 ->系統金鑰 ->webpubsub_extension。 不過，當您使用本機函式時，不需要此金鑰。

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

範例

C#

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

當伺服器可以檢查和拒絕用戶端要求，或直接將訊息傳送給呼叫者端時，WebPubSubTrigger 繫結也支援同步處理情節中的傳回值 (例如，系統 Connect 和使用者事件)。 Connect 事件遵守 ConnectEventResponse 和 EventErrorResponse，而使用者事件遵守 UserEventResponse 和 EventErrorResponse，不符合目前情節的 rest 型別會予以忽略。 如果傳回 EventErrorResponse，服務會卸除用戶端連線。

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

JavaScript 模型 v4

下列範例顯示 Web PubSub 觸發程序 JavaScript 函式。

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

當伺服器可以檢查和拒絕用戶端要求，或直接將訊息傳送給要求用戶端時，WebPubSubTrigger 繫結也支援同步處理情節中的傳回值 (例如，系統 Connect 和使用者事件)。 在 JavaScript 弱型別語言中，它會針對物件索引鍵還原序列化。 此外，與 rest 物件相比較，EventErrorResponse 具有最高優先順序，如果 code 位於傳回中，則會剖析為 EventErrorResponse，並卸除用戶端連線。

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

JavaScript 模型 v3

在 function.json 中定義觸發程序繫結。

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

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

當伺服器可以檢查和拒絕用戶端要求，或直接將訊息傳送給要求用戶端時，WebPubSubTrigger 繫結也支援同步處理情節中的傳回值 (例如，系統 Connect 和使用者事件)。 在 JavaScript 弱型別語言中，它會針對物件索引鍵還原序列化。 此外，與 rest 物件相比較，EventErrorResponse 具有最高優先順序，如果 code 位於傳回中，則會剖析為 EventErrorResponse，並卸除用戶端連線。

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

屬性和註釋

在 C# 類別庫中，使用 WebPubSubTrigger 屬性。

以下是方法簽章中的 WebPubSubTrigger 屬性：

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

如需完整範例，請參閱 C# 範例。

組態

下表說明您在 function.json 檔案中設定的繫結設定屬性。

function.json 屬性	屬性內容	描述
type	n/a	必要項目 - 必須設定為 webPubSubTrigger。
direction	n/a	必要項目 - 必須設定為 in。
name	n/a	必要項目 - 函式程式碼中用於接收事件資料之參數的變數名稱。
中樞	中樞	必要 - 針對要觸發的函式，此值必須設為其 Web PubSub 中樞的名稱。 我們支援將屬性中的該值設定為較高的優先順序，或者可以在應用程式設定中將其設定為全域值。
eventType	WebPubSubEventType	必要 - 針對要觸發的函式，此值必須設為其訊息事件類型。 該值應為 user 或 system。
eventName	EventName	必要 - 針對要觸發的函式，此值必須設為其訊息事件。 針對 system 事件類型，事件名稱應位於 connect、connected、disconnected 中。 針對使用者定義的子通訊協定，事件名稱為 message。 針對系統支援的子通訊協定 json.webpubsub.azure.v1.，事件名稱為使用者定義的事件名稱。
connection	連線	選擇性 - 指定上游 Azure Web PubSub 服務的應用程式設定名稱或設定集合名稱。 此值用於簽章驗證。 而且此值依預設會使用應用程式設定「WebPubSubConnectionString」進行自動解析。 而且 null 表示不需要驗證，而且一律會成功。

使用方式

在 C# 中，WebPubSubEventRequest 為已辨識型別繫結參數，剩餘參數則會由參數名稱繫結。 請查看下表，以取得可用的參數和型別。

在類似 JavaScript 的弱型別語言中，name 中的 function.json 會用來繫結與以下對應表有關的觸發程序物件。 當 name 設定為 data (作為觸發程序輸入的繫結物件) 時，會遵守 dataType 中的 function.json，以據此轉換訊息。 所有參數都可以從 context.bindingData.<BindingName> 進行讀取，而且會進行 JObject 轉換。

繫結名稱	繫結類型	描述	屬性
要求	WebPubSubEventRequest	描述上游要求	屬性會因不同的事件類型而有所不同，包括衍生類別 ConnectEventRequest、ConnectedEventRequest、UserEventRequest 和 DisconnectedEventRequest
connectionContext	WebPubSubConnectionContext	一般要求資訊	EventType、EventName、Hub、ConnectionId、UserId、Headers、Origin、Signature、States
資料	BinaryData、string、Stream、byte[]	在使用者 message 事件中向用戶端要求訊息資料	-
dataType	WebPubSubDataType	要求訊息 dataType，支援 binary、text、json	-
claims	IDictionary<string, string[]>	系統 connect 要求中的使用者宣告	-
query	IDictionary<string, string[]>	系統 connect 要求中的使用者查詢	-
子通訊協定	IList<string>	系統 connect 要求中可用的子通訊協定	-
clientCertificates	IList<ClientCertificate>	系統 connect 要求中用戶端的憑證指紋清單	-
reason	string	系統 disconnected 要求中的原因	-

重要

在 C# 中，支援多個型別的參數必須放在第一個，也就是預設 BinaryData 型別以外的 request 或 data 參數，讓函式正確繫結。

傳回回應

WebPubSubTrigger 會遵守客戶針對 connect 的同步事件和使用者事件所傳回的回應。 只有相符的回應會傳回至服務，否則會將其忽略。 此外，WebPubSubTrigger 傳回物件支援使用者 SetState() 及 ClearStates()，以管理連線的中繼資料。 延伸模組會將傳回值的結果與來自要求 WebPubSubConnectionContext.States 的原始結果合併。 現有索引鍵中的值會覆寫，並新增新索引鍵中的值。

傳回類型	描述	屬性
ConnectEventResponse	connect 事件的回應	Groups、Roles、UserId、Subprotocol
UserEventResponse	使用者事件的回應	DataType、Data
EventErrorResponse	同步事件的錯誤回應	Code、ErrorMessage
*WebPubSubEventResponse	支援的基本回應類型 (適用於不確定傳回案例)	-

輸入繫結

我們的延伸模組提供兩個以不同需求為目標的輸入繫結。

• WebPubSubConnection

  若要讓用戶端連線到 Azure Web PubSub 服務，它必須知道服務端點 URL 和有效的存取權杖。 WebPubSubConnection 輸入繫結會產生必要的資訊，因此用戶端本身不需要處理這個權杖產生。 因為權杖是限時的，且可用來驗證連線的特定使用者，所以請不要快取權杖或者在用戶端之間共用權杖。 搭配此輸入繫結使用的 HTTP 觸發程序可以供用戶端用來擷取連線資訊。

• WebPubSubContext

  使用 Static Web Apps 時，HttpTrigger 是唯一支援的觸發程序，而且在 Web PubSub 情節下，我們提供 WebPubSubContext 輸入繫結，可協助使用者從 Web PubSub 通訊協定下的服務端還原序列化上游 HTTP 要求。 因此，與 WebPubSubTrigger 比較，客戶可以取得類似的結果，以便輕鬆地在函式中處理。 請參閱下面的範例。 搭配 HttpTrigger 使用時，客戶必須相應地在事件處理常式中設定 HttpTrigger 公開 URL。

範例 - WebPubSubConnection

以下範例示範 C# 函式，該函式會使用輸入繫結來取得 Web PubSub 連線資訊，並且透過 HTTP 傳回。 在以下範例中，UserId 會透過用戶端要求查詢組件傳入，例如 ?userid={User-A}。

C#

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

JavaScript 模型 v4

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

JavaScript 模型 v3

在 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"
    }
  ]
}

在 index.js 中定義函式。

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

已驗證權杖

如果函式是由已驗證的用戶端觸發，您可以將使用者識別碼宣告新增至產生的權杖。 您可以使用 [App Service 驗證]，輕鬆地將驗證新增至函數應用程式。

App Service 驗證會設定名為 x-ms-client-principal-id 和 x-ms-client-principal-name 的 HTTP 標頭，這些標頭分別包含已驗證使用者的用戶端主體識別碼和名稱。

您可以使用繫結運算式 ({headers.x-ms-client-principal-id} 或 {headers.x-ms-client-principal-name})，將繫結的 UserId 屬性設為任一標頭的值。

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

C#

注意

受限於繫結參數型別不支援傳遞清單或陣列，因此並非伺服器 SDK 的所有參數都完全支援 WebPubSubConnection，特別是 roles，同時也包含 groups 和 expiresAfter。 如果客戶需要在函式中新增角色或延遲建置存取權杖，建議使用適用於 C# 的伺服器 SDK。

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

JavaScript 模型 v4

注意

受限於繫結參數型別不支援傳遞清單或陣列，因此並非伺服器 SDK 的所有參數都完全支援 WebPubSubConnection，特別是 roles，同時也包含 groups 和 expiresAfter。 如果客戶需要在函式中新增角色或延遲建置存取權杖，建議使用適用於 JavaScript 的伺服器 SDK。

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

JavaScript 模型 v3

注意

受限於繫結參數型別不支援傳遞清單或陣列，因此並非伺服器 SDK 的所有參數都完全支援 WebPubSubConnection，特別是 roles，同時也包含 groups 和 expiresAfter。 如果客戶需要在函式中新增角色或延遲建置存取權杖，建議使用適用於 JavaScript 的伺服器 SDK。

在 function.json 中定義輸入繫結。

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

在 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();
};

範例 - WebPubSubContext

以下範例示範 C# 函式，該函式會使用 connect 事件類型下的輸入繫結來取得 Web PubSub 上游要求資訊，並且透過 HTTP 將其傳回。

C#

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

JavaScript 模型 v4

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

JavaScript 模型 v3

在 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"
    }
  ]
}

在 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} };
};

組態

WebPubSubConnection

下表說明您在 function.json 檔案中設定的繫結設定屬性內容和 WebPubSubConnection 屬性。

function.json 屬性	屬性內容	描述
type	n/a	必須設定為 webPubSubConnection
direction	n/a	必須設定為 in
name	n/a	函式程式碼中用於輸入連線繫結物件的變數名稱。
中樞	中樞	必要 - 針對要觸發的函式，此值必須設為其 Web PubSub 中樞的名稱。 我們支援將屬性中的該值設定為較高的優先順序，或者可以在應用程式設定中將其設定為全域值。
userId	UserId	選擇性：要在存取金鑰權杖中設定的使用者識別碼宣告值。
connection	連線	必要 - 包含 Web PubSub 服務連接字串的應用程式設定名稱 (預設值為「WebPubSubConnectionString」)。

WebPubSubContext

下表說明您在 function.json 檔案中設定的繫結設定屬性內容和 WebPubSubContext 屬性。

function.json 屬性	屬性內容	描述
type	n/a	必須設定為 webPubSubContext。
direction	n/a	必須設定為 in。
name	n/a	函式程式碼中用於輸入 Web PubSub 要求的變數名稱。
connection	連線	選擇性 - 指定上游 Azure Web PubSub 服務的應用程式設定名稱或設定集合名稱。 此值用於濫用保護和簽章驗證。 此值預設為使用「WebPubSubConnectionString」進行自動解析。 而且 null 表示不需要驗證，而且一律會成功。

使用方式

WebPubSubConnection

C#

WebPubSubConnection 提供下列屬性。

繫結名稱	繫結類型	描述
BaseUri	URI	Web PubSub 用戶端連線 URI。
URI	URI	Web PubSub 連線的絕對 URI，其中包含根據要求所產生的 AccessToken。
AccessToken	string	根據要求 UserId 和服務資訊所產生的 AccessToken。

JavaScript 模型 v4

WebPubSubConnection 提供下列屬性。

繫結名稱	描述
baseUrl	Web PubSub 用戶端連線 URI。
URL	Web PubSub 連線的絕對 URI，其中包含根據要求所產生的 AccessToken。
accessToken	根據要求 UserId 和服務資訊所產生的 AccessToken。

JavaScript 模型 v3

WebPubSubConnection 提供下列屬性。

繫結名稱	描述
baseUrl	Web PubSub 用戶端連線 URI。
URL	Web PubSub 連線的絕對 URI，其中包含根據要求所產生的 AccessToken。
accessToken	根據要求 UserId 和服務資訊所產生的 AccessToken。

WebPubSubContext

WebPubSubContext 提供下列屬性。

繫結名稱	繫結類型	描述	屬性
要求	WebPubSubEventRequest	用戶端要求，請參閱下表以取得詳細資料。	要求標頭的 WebPubSubConnectionContext 與其他從要求本文還原序列化的屬性可描述要求，例如，適用於 DisconnectedEventRequest 的 Reason。
回覆	HttpResponseMessage	延伸模組主要會針對 AbuseProtection 和錯誤案例建置回應。	-
errorMessage	string	描述處理上游要求時的錯誤詳細資料。	-
hasError	bool	旗標，指出它是否為有效的 Web PubSub 上游要求。	-
isPreflight	bool	旗標，指出它是否為 AbuseProtection 的預檢要求。	-

針對 WebPubSubEventRequest，它會還原序列化為不同類別，以提供有關要求情節的不同資訊。 若為 PreflightRequest 或無效案例，使用者可以檢查旗標 IsPreflight 與 HasError 以進行了解。 建議您直接傳回系統組建回應 WebPubSubContext.Response，或客戶可以視需要記錄錯誤。 在不同的情節中，客戶可以讀取要求屬性，如下所示。

衍生類別	描述	屬性
PreflightRequest	用於 AbuseProtection (當 IsPreflight 為 true 時)	-
ConnectEventRequest	用於系統 Connect 事件類型	Claims、Query、Subprotocols、ClientCertificates
ConnectedEventRequest	用於系統 Connected 事件類型	-
UserEventRequest	用於使用者事件類型	Data、DataType
DisconnectedEventRequest	用於系統 Disconnected 事件類型	原因

注意

雖然 WebPubSubContext 是輸入繫結，可在 HttpTrigger 下提供類似的要求還原序列化方式 (相較於 WebPubSubTrigger)，但還是有所限制，亦即不支援合併後的連線狀態。 服務端仍會遵守傳回回應，但使用者需要自行建置回應。 如果使用者必須設定事件回應，您應該傳回包含 ConnectEventResponse 的 HttpResponseMessage，或者使用者事件的訊息作為回應本文，並將具有索引鍵 ce-connectionstate 的連線狀態，放在回應標頭中。

輸出繫結

使用 Web PubSub 輸出繫結來叫用 Azure Web PubSub 服務，以執行某些動作。 您可以將訊息廣播至：

• 所有已連線的用戶端
• 將以驗證的用戶端連線至特定使用者
• 已加入特定群組的已連線用戶端
• 特定用戶端連線

輸出繫結也可讓您管理用戶端和群組，以及以群組特定 connectionId 為目標的授與/撤銷權限。

• 將連線新增至群組
• 將使用者新增至群組
• 從群組移除連線
• 移除群組中的使用者
• 從所有群組中移除使用者
• 關閉所有用戶端連線
• 關閉特定用戶端連線
• 關閉群組中的連線
• 連線的授與權限
• 連線的撤銷權限

如需安裝和設定細節的相關資訊，請參閱概觀。

範例

C#

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

JavaScript 模型 v4

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`
        }]);
    }
});

JavaScript 模型 v3

在 functions.json 中定義繫結。

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

在 index.js 中定義函式。

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

WebPubSubAction

WebPubSubAction 是輸出繫結的基本抽象類型。 衍生型別代表動作伺服器希望服務進行叫用。

C#

在 C# 語言中，我們在 WebPubSubAction 下提供了一些靜態方法，以協助探索可用的動作。 例如，使用者可以透過呼叫 WebPubSubAction.CreateSendToAllAction() 來建立 SendToAllAction。

衍生類別	屬性
SendToAllAction	Data、DataType、Excluded
SendToGroupAction	Group、Data、DataType、Excluded
SendToUserAction	UserId、Data、DataType
SendToConnectionAction	ConnectionId、Data、DataType
AddUserToGroupAction	UserId、Group
RemoveUserFromGroupAction	UserId、Group
RemoveUserFromAllGroupsAction	UserId
AddConnectionToGroupAction	ConnectionId、Group
RemoveConnectionFromGroupAction	ConnectionId、Group
CloseAllConnectionsAction	Excluded、Reason
CloseClientConnectionAction	ConnectionId、Reason
CloseGroupConnectionsAction	Group、Excluded、Reason
GrantPermissionAction	ConnectionId、Permission、TargetName
RevokePermissionAction	ConnectionId、Permission、TargetName

JavaScript 模型 v4

在類似 javascript 的弱型別語言中，actionName 是解析型別的索引鍵參數，可用的動作如下所示。

ActionName	屬性
sendToAll	Data、DataType、Excluded
sendToGroup	Group、Data、DataType、Excluded
sendToUser	UserId、Data、DataType
sendToConnection	ConnectionId、Data、DataType
addUserToGroup	UserId、Group
removeUserFromGroup	UserId、Group
removeUserFromAllGroups	UserId
addConnectionToGroup	ConnectionId、Group
removeConnectionFromGroup	ConnectionId、Group
closeAllConnections	Excluded、Reason
closeClientConnection	ConnectionId、Reason
closeGroupConnections	Group、Excluded、Reason
grantPermission	ConnectionId、Permission、TargetName
revokePermission	ConnectionId、Permission、TargetName

重要

如果資料類型設定為 json 或 text，則傳送訊息相關動作中的訊息資料屬性必須是 string，以避免資料轉換語意模糊。 請使用 JSON.stringify() 來轉換所需的 JSON 物件。 這會套用至任何使用訊息屬性的位置，例如搭配 WebPubSubTrigger 使用的 UserEventResponse.Data。

當資料類型設定為 binary 時，允許使用支援 dataType 為 binary (於 function.json 中設定) 的繫結，請參閱觸發程序和繫結定義以取得詳細資料。

JavaScript 模型 v3

在類似 javascript 的弱型別語言中，actionName 是解析型別的索引鍵參數，可用的動作如下所示。

ActionName	屬性
sendToAll	Data、DataType、Excluded
sendToGroup	Group、Data、DataType、Excluded
sendToUser	UserId、Data、DataType
sendToConnection	ConnectionId、Data、DataType
addUserToGroup	UserId、Group
removeUserFromGroup	UserId、Group
removeUserFromAllGroups	UserId
addConnectionToGroup	ConnectionId、Group
removeConnectionFromGroup	ConnectionId、Group
closeAllConnections	Excluded、Reason
closeClientConnection	ConnectionId、Reason
closeGroupConnections	Group、Excluded、Reason
grantPermission	ConnectionId、Permission、TargetName
revokePermission	ConnectionId、Permission、TargetName

重要

如果資料類型設定為 json 或 text，則傳送訊息相關動作中的訊息資料屬性必須是 string，以避免資料轉換語意模糊。 請使用 JSON.stringify() 來轉換所需的 JSON 物件。 這會套用至任何使用訊息屬性的位置，例如搭配 WebPubSubTrigger 使用的 UserEventResponse.Data。

當資料類型設定為 binary 時，允許使用支援 dataType 為 binary (於 function.json 中設定) 的繫結，請參閱觸發程序和繫結定義以取得詳細資料。

組態

WebPubSub

下表說明您在 function.json 檔案中設定的繫結設定屬性內容和 WebPubSub 屬性。

function.json 屬性	屬性內容	描述
type	n/a	必須設定為 webPubSub
direction	n/a	必須設定為 out
name	n/a	函式程式碼中用於輸出繫結物件的變數名稱。
中樞	中樞	針對要觸發的函式，此值必須設為其 Web PubSub 中樞的名稱。 我們支援將屬性中的該值設定為較高的優先順序，或者可以在應用程式設定中將其設定為全域值。
connection	連線	包含 Web PubSub 服務連接字串的應用程式設定名稱 (預設值為「WebPubSubConnectionString」)。

疑難排解

設定主控台記錄

如果您想要深入了解針對服務提出的要求，您也可以輕鬆地啟用主控台記錄。

下一步

使用這些資源開始建置自己的應用程式：

教學課程：在 Azure Web PubSub 中發佈及訂閱訊息

教學課程：使用 Azure Web PubSub 建立簡單的聊天室

教學課程：使用服務支援的子通訊協定進行用戶端串流

教學課程：使用 Azure Functions 和 Web PubSub 建置無伺服器聊天

教學課程：設定事件接聽程式

探索即時示範

探索更多 Azure Web PubSub 範例