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

發行項
04/15/2024

此參考說明如何在 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 入口網站線上使用)	新增繫結	若要更新現有的繫結延伸模組，而不需重新發行您的函式應用程式，請參閱更新您的延伸模組。

重要概念

此圖顯示 Azure Web PubSub 服務搭配 Function 應用程式使用的工作流程。

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

取得函式系統金鑰的螢幕擷取畫面。

範例

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

下列範例顯示 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"
          };
    }
});

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

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
資料		在使用者 `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}。

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

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

注意

受限於繫結參數型別不支援傳遞清單或陣列，因此並非伺服器 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);
}

注意

受限於繫結參數型別不支援傳遞清單或陣列，因此並非伺服器 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 };
    },
});

注意

在 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 將其傳回。

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

在 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

WebPubSubConnection 提供下列屬性。

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

WebPubSubConnection 提供下列屬性。

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

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 為目標的授與/撤銷權限。

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

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

範例

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

在 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# 語言中，我們在 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 的弱型別語言中，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 的弱型別語言中，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

重要

當資料類型設定為 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 範例

共用方式為

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

新增至您的 Functions 應用程式

重要概念

觸發程序繫結

範例

屬性和註釋

組態

使用方式

傳回回應

輸入繫結

範例 - `WebPubSubConnection`

已驗證權杖

範例 - `WebPubSubContext`

組態

WebPubSubConnection

WebPubSubContext

使用方式

WebPubSubConnection

WebPubSubContext

輸出繫結

範例

WebPubSubAction

組態

WebPubSub

疑難排解

設定主控台記錄

下一步

意見反應

其他資源

共用方式為

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

新增至您的 Functions 應用程式

重要概念

觸發程序繫結

範例

屬性和註釋

組態

使用方式

傳回回應

輸入繫結

範例 - WebPubSubConnection

已驗證權杖

範例 - WebPubSubContext

組態

WebPubSubConnection

WebPubSubContext

使用方式

WebPubSubConnection

WebPubSubContext

輸出繫結

範例

WebPubSubAction

組態

WebPubSub

疑難排解

設定主控台記錄

下一步

意見反應

其他資源

範例 - `WebPubSubConnection`

範例 - `WebPubSubContext`