Merge pull request #184406 from JialinXin/awps-serverless-f2

[WebPubSub] Minor updates to serverless tutorials.

Author: PMEds28

articles/azure-web-pubsub/howto-develop-eventhandler.md

@@ -22,30 +22,34 @@ The data sending from the service to the server is always in CloudEvents `binary
 
 ## Upstream and Validation
 
-When configuring the webhook endpoint, the URL can use `{event}` parameter to define a URL template. The service calculates the value of the webhook URL dynamically when the client request comes in. For example, when a request `/client/hubs/chat` comes in, with a configured event handler URL pattern `http://host.com/api/{event}` for hub `chat`, when the client connects, it will first POST to this URL: `http://host.com/api/connect`. This can be useful when a PubSub WebSocket client sends custom events, that the event handler helps dispatch different events to different upstream. Note that the `{event}` parameter is not allowed in the URL domain name.
+When configuring the webhook endpoint, the URL can use `{event}` parameter to define a URL template. The service calculates the value of the webhook URL dynamically when the client request comes in. For example, when a request `/client/hubs/chat` comes in, with a configured event handler URL pattern `http://host.com/api/{event}` for hub `chat`, when the client connects, it will first POST to this URL: `http://host.com/api/connect`. The parameter can be useful when a PubSub WebSocket client sends custom events, that the event handler helps dispatch different events to different upstream. Note that the `{event}` parameter is not allowed in the URL domain name.
 
-When setting up the event handler upstream through Azure portal or CLI, the service follows the [CloudEvents Abuse Protection](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#4-abuse-protection) to validate the upstream webhook. Every registered upstream webhook URL will be validated by this mechanism. The `WebHook-Request-Origin` request header is set to the service domain name `xxx.webpubsub.azure.com`, and it expects the response having header `WebHook-Allowed-Origin` to contain this domain name or `*`.
+When setting up the event handler upstream through Azure portal or CLI, the service follows the [CloudEvents Abuse Protection](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#4-abuse-protection) to validate the upstream webhook. Every registered upstream webhook URL will be validated by this mechanism. The `WebHook-Request-Origin` request header is set to the service domain name `xxx.webpubsub.azure.com`, and it expects the response to have a header `WebHook-Allowed-Origin` to contain this domain name or `*`.
 
-When doing the validation, the `{event}` parameter is resolved to `validate`. For example, when trying to set the URL to `http://host.com/api/{event}`, the service tries to **OPTIONS** a request to `http://host.com/api/validate` and only when the response is valid the configure can be set successfully.
+When doing the validation, the `{event}` parameter is resolved to `validate`. For example, when trying to set the URL to `http://host.com/api/{event}`, the service will try to **OPTIONS** a request to `http://host.com/api/validate`. And only when the response is valid, the configuration can be set successfully.
 
 For now, we do not support [WebHook-Request-Rate](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#414-webhook-request-rate) and [WebHook-Request-Callback](https://github.com/cloudevents/spec/blob/v1.0/http-webhook.md#413-webhook-request-callback).
 
 ## Authentication between service and webhook
 
 - Anonymous mode
 - Simple Auth with `?code=<code>` is provided through the configured Webhook URL as query parameter.
-- Use AAD Auth, check [here](howto-use-managed-identity.md) for details.
+- Use Azure Active Directory(Azure AD) authentication, check [here](howto-use-managed-identity.md) for details.
    - Step1: Enable Identity for the Web PubSub service
    - Step2: Select from existing AAD application that stands for your webhook web app
 
 ## Configure event handler
 
 ### Configure through Azure portal
 
-Find your Azure Web PubSub service from **Azure portal**. Navigate to **Settings** and enter your hub-name. Then click **Add** to configure your server side webhook URL. Don't forget to click **Save** when finish.
+Find your Azure Web PubSub service from **Azure portal**. Navigate to **Settings**. Then select **Add** to configure your server-side webhook URL. For an existing hub configuration, select **...** on right side will navigate to the same editing page.
 
 :::image type="content" source="media/quickstart-serverless/set-event-handler.png" alt-text="Screenshot of setting the event handler.":::
 
+Then in the below editing page, you'd need to configure hub name, server webhook URL, and select `user` and `system` events you'd like to subscribe. Finally select **Save** when everything is done. 
+
+:::image type="content" source="media/quickstart-serverless/edit-event-handler.png" alt-text="Screenshot of editing the event handler.":::
+
 ### Configure through Azure CLI
 
 Use the Azure CLI [**az webpubsub hub**](/cli/azure/webpubsub/hub) group commands to configure the event handler settings.

articles/azure-web-pubsub/media/quickstart-serverless/edit-event-handler.png

@@ -142,7 +142,7 @@ In this tutorial, you learn how to:
    - Update `index.cs` and replace `Run` function with following codes.
         ```c#
         [FunctionName("index")]
-        public static IActionResult Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req)
+        public static IActionResult Run([HttpTrigger(AuthorizationLevel.Anonymous)] HttpRequest req, ILogger log)
         {
             string indexFile = "index.html";
             if (Environment.GetEnvironmentVariable("HOME") != null)
@@ -203,14 +203,18 @@ In this tutorial, you learn how to:
         ```c#
         [FunctionName("negotiate")]
         public static WebPubSubConnection Run(
-            [HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req,
+            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)] HttpRequest req,
             [WebPubSubConnection(Hub = "simplechat", UserId = "{headers.x-ms-client-principal-name}")] WebPubSubConnection connection,
             ILogger log)
         {
             log.LogInformation("Connecting...");
             return connection;
         }
         ```
+   - Add below `using` statements in header to resolve required dependencies.
+        ```c#
+        using Microsoft.Azure.WebJobs.Extensions.WebPubSub;
+        ```
 
 5. Create a `message` function to broadcast client messages through service.
    ```bash
@@ -264,22 +268,26 @@ In this tutorial, you learn how to:
         ```c#
         [FunctionName("message")]
         public static async Task<UserEventResponse> Run(
-            [WebPubSubTrigger(WebPubSubEventType.User, "message")] UserEventRequest request,
+            [WebPubSubTrigger("simplechat", WebPubSubEventType.User, "message")] UserEventRequest request,
             BinaryData data,
             WebPubSubDataType dataType,
             [WebPubSub(Hub = "simplechat")] IAsyncCollector<WebPubSubAction> actions)
         {
             await actions.AddAsync(WebPubSubAction.CreateSendToAllAction(
-                BinaryData.FromString($"[{request.ConnectionContext.UserId}] {message.ToString()}"),
-                dataType
-            );
+                BinaryData.FromString($"[{request.ConnectionContext.UserId}] {data.ToString()}"),
+                dataType));
             return new UserEventResponse
             {
                 Data = BinaryData.FromString("[SYSTEM] ack"),
                 DataType = WebPubSubDataType.Text
             };
         }
         ```
+   - Add below `using` statements in header to resolve required dependencies.
+        ```c#
+        using Microsoft.Azure.WebJobs.Extensions.WebPubSub;
+        using Microsoft.Azure.WebPubSub.Common;
+        ```
 
 6. Add the client single page `index.html` in the project root folder and copy content as below.
     ```html

articles/azure-web-pubsub/media/quickstart-serverless/set-event-handler.png

@@ -75,7 +75,7 @@ In this tutorial, you learn how to:
     ```
    b. Run command to install specific function extension package.
     ```bash
-    func extensions install --package Microsoft.Azure.WebJobs.Extensions.WebPubSub --version 1.0.0
+    func extensions install --package Microsoft.Azure.WebJobs.Extensions.WebPubSub --version 1.1.0
     ```
 
 3. Create an `index` function to read and host a static web page for clients.
@@ -204,6 +204,10 @@ In this tutorial, you learn how to:
             return connection;
         }
         ```
+   - Add below `using` statements in header to resolve required dependencies.
+        ```c#
+        using Microsoft.Azure.WebJobs.Extensions.WebPubSub;
+        ```
 
 5. Create a `notification` function to generate notifications with `TimerTrigger`.
    ```bash
@@ -265,6 +269,11 @@ In this tutorial, you learn how to:
             return value.ToString("0.000");
         }
         ``` 
+   - Add below `using` statements in header to resolve required dependencies.
+        ```c#
+        using Microsoft.Azure.WebJobs.Extensions.WebPubSub;
+        using Microsoft.Azure.WebPubSub.Common;
+        ```
 
 6. Add the client single page `index.html` in the project root folder and copy content as below.
     ```html
@@ -310,14 +319,14 @@ In this tutorial, you learn how to:
 
     :::image type="content" source="media/quickstart-serverless/copy-connection-string.png" alt-text="Screenshot of copying the Web PubSub connection string.":::
 
-    Run command below in the function folder to set the service connection string. Replace `<connection-string`> with your value as needed.
+    Run command below in the function folder to set the service connection string. Replace `<connection-string>` with your value as needed.
 
     ```bash
     func settings add WebPubSubConnectionString "<connection-string>"
     ```
 
     > [!NOTE]
-    > `TimerTrigger` used in the sample has dependency on Azure Storage, but you can use local storage emulator when the Function is running locally. If you got some error like `There was an error performing a read operation on the Blob Storage Secret Repository. Please ensure the 'AzureWebJobsStorage' connection string is valid.` You need to download and enable [Storage Emulator](../storage/common/storage-use-emulator.md).
+    > `TimerTrigger` used in the sample has dependency on Azure Storage, but you can use local storage emulator when the Function is running locally. If you got some error like `There was an error performing a read operation on the Blob Storage Secret Repository. Please ensure the 'AzureWebJobsStorage' connection string is valid.`, you'll need to download and enable [Storage Emulator](../storage/common/storage-use-emulator.md).
 
     Now you're able to run your local function by command below.