Skip to content

Commit 353ad86

Browse files
PMEds28PMEds28
authored
Merge pull request #202118 from MicrosoftDocs/main
Publish to Live, Monday 4AM PST, 6/20
2 parents 431acf5 + f372437 commit 353ad86

File tree

22 files changed

+732
-141
lines changed

22 files changed

+732
-141
lines changed

‎articles/azure-arc/vmware-vsphere/quick-start-connect-vcenter-to-arc-using-script.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,10 @@ Use the following instructions to run the script, depending on which operating s
9797

9898
### Windows
9999

100-
1. Open a PowerShell window and go to the folder where you've downloaded the PowerShell script.
100+
1. Open a PowerShell window as an Administrator and go to the folder where you've downloaded the PowerShell script.
101+
102+
> [!NOTE]
103+
> On Windows workstations, the script must be run in PowerShell window and not in PowerShell Integrated Script Editor (ISE) as PowerShell ISE doesn't display the input prompts from Azure CLI commands. If the script is run on PowerShell ISE, it could appear as though the script is stuck while it is waiting for input.
101104
102105
2. Run the following command to allow the script to run, because it's an unsigned script. (If you close the session before you complete all the steps, run this command again for the new session.)
103106

‎articles/azure-monitor/logs/custom-fields.md

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22
title: Custom fields in Azure Monitor (Preview) | Microsoft Docs
33
description: The Custom Fields feature of Azure Monitor allows you to create your own searchable fields from records in a Log Analytics workspace that add to the properties of a collected record. This article describes the process to create a custom field and provides a detailed walkthrough with a sample event.
44
ms.topic: conceptual
5-
author: bwren
6-
ms.author: bwren
5+
author: guywild
6+
ms.author: guywild
7+
ms.reviewer: roygal
78
ms.date: 10/20/2021
89

910
---
@@ -76,17 +77,13 @@ The following section walks through a complete example of creating a custom fiel
7677

7778
We enter the following query to return all events from Service Control Manager that have an Event ID of 7036 which is the event that indicates a service starting or stopping.
7879

79-
![Screenshot shows a query for an event source and ID.](media/custom-fields/query.png)
80+
![Screenshot showing a query for an event source and ID.](media/custom-fields/query.png)
8081

81-
We then select and expand any record with event ID 7036.
82+
We then right-click on any record with event ID 7036 and select **Extract fields from \`Event`**.
8283

83-
![Source record](media/custom-fields/source-record.png)
84+
![Screenshot showing the Copy and Extract fields options, which are available when you right-click a record from the list of results.](media/custom-fields/extract-fields.png)
8485

85-
We define custom fields by clicking the ellipsis next to the top property.
86-
87-
![Extract fields](media/custom-fields/extract-fields.png)
88-
89-
The **Field Extraction Wizard** is opened, and the **EventLog** and **EventID** fields are selected in the **Main Example** column. This indicates that the custom field will be defined for events from the System log with an event ID of 7036. This is sufficient so we don’t need to select any other fields.
86+
The **Field Extraction Wizard** opens with the **EventLog** and **EventID** fields selected in the **Main Example** column. This indicates that the custom field will be defined for events from the System log with an event ID of 7036. This is sufficient so we don’t need to select any other fields.
9087

9188
![Main example](media/custom-fields/main-example.png)
9289

‎articles/azure-monitor/logs/media/custom-fields/extract-fields.png

30 KB
Loading

‎articles/azure-monitor/logs/quick-create-workspace.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,6 +200,7 @@ For more information about Azure Resource Manager templates, see [Azure Resource
200200
}
201201
}
202202
```
203+
---
203204

204205
## Troubleshooting
205206

‎articles/azure-signalr/TOC.yml

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,18 @@
155155
- name: Azure CLI
156156
href: /cli/azure/signalr
157157
- name: REST API
158-
href: /rest/api/signalr
158+
items:
159+
- name: Control plane
160+
href: /rest/api/signalr
161+
- name: Data plane
162+
href: signalr-reference-data-plane-rest-api.md
163+
items:
164+
- name: Versions
165+
items:
166+
- name: v1
167+
href: swagger/signalr-data-plane-rest-v1.md
168+
- name: v1-preview
169+
href: swagger/signalr-data-plane-rest-v1-preview.md
159170
- name: ASP.NET Core SignalR
160171
href: /aspnet/core/signalr/introduction
161172
- name: Azure SignalR Service Protocol

‎articles/azure-signalr/media/signalr-reference-data-plane-rest-api/serverless-arch.png

18.9 KB
Loading

‎articles/azure-signalr/signalr-reference-data-plane-rest-api.md

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
title: Azure SignalR service data plane REST API reference
3+
description: Describes the REST APIs Azure SignalR service supports to manage the connections and send messages to them.
4+
author: vicancy
5+
ms.author: lianwei
6+
ms.service: signalr
7+
ms.topic: reference
8+
ms.date: 06/09/2022
9+
---
10+
11+
# Azure SignalR service data plane REST API reference
12+
13+
> [!NOTE]
14+
>
15+
> Azure SignalR Service only supports using REST API to manage clients connected using ASP.NET Core SignalR. Clients connected using ASP.NET SignalR use a different data protocol that is not currently supported.
16+
17+
On top of the classical client-server pattern, Azure SignalR Service provides a set of REST APIs so that you can easily integrate real-time functionality into your server-less architecture.
18+
19+
<a name="serverless"></a>
20+
21+
## Typical Server-less Architecture with Azure Functions
22+
23+
The following diagram shows a typical server-less architecture using Azure SignalR Service with Azure Functions.
24+
25+
:::image type="content" source="./media/signalr-reference-data-plane-rest-api/serverless-arch.png" alt-text="Diagram of a typical serverless architecture for Azure SignalR service":::
26+
27+
- `negotiate` function returns a negotiation response and redirects all clients to SignalR Service.
28+
- `broadcast` function calls SignalR Service's REST API. Then SignalR Service will broadcast the message to all connected clients.
29+
30+
In a server-less architecture, clients still have persistent connections to the SignalR Service.
31+
Since there's no application server to handle traffic, clients are in `LISTEN` mode, which means they can only receive messages but can't send messages.
32+
SignalR Service will disconnect any client that sends messages because it's an invalid operation.
33+
34+
You can find a complete sample of using SignalR Service with Azure Functions at [here](https://github.com/aspnet/AzureSignalR-samples/tree/master/samples/RealtimeSignIn).
35+
36+
## API
37+
38+
The following table shows all versions of REST API we have for now. You can also find the swagger file for each version of REST API.
39+
40+
API Version | Status | Port | Doc | Spec
41+
---|---|---|---|---
42+
`1.0` | Latest | Standard | [Doc](./swagger/signalr-data-plane-rest-v1.md) | [swagger](https://github.com/Azure/azure-signalr/blob/dev/docs/swagger/v1.json)
43+
`1.0-preview` | Obsolete | Standard | [Doc](./swagger/signalr-data-plane-rest-v1-preview.md) | [swagger](https://github.com/Azure/azure-signalr/blob/dev/docs/swagger/v1-preview.json)
44+
45+
The latest available APIs are listed as following.
46+
47+
48+
| API | Path |
49+
| ---- | ---------- |
50+
| [Broadcast a message to all clients connected to target hub.](./swagger/signalr-data-plane-rest-v1.md#broadcast-a-message-to-all-clients-connected-to-target-hub) | `POST /api/v1/hubs/{hub}` |
51+
| [Broadcast a message to all clients belong to the target user.](./swagger/signalr-data-plane-rest-v1.md#broadcast-a-message-to-all-clients-belong-to-the-target-user) | `POST /api/v1/hubs/{hub}/users/{id}` |
52+
| [Send message to the specific connection.](./swagger/signalr-data-plane-rest-v1.md#send-message-to-the-specific-connection) | `POST /api/v1/hubs/{hub}/connections/{connectionId}` |
53+
| [Check if the connection with the given connectionId exists](./swagger/signalr-data-plane-rest-v1.md#check-if-the-connection-with-the-given-connectionid-exists) | `GET /api/v1/hubs/{hub}/connections/{connectionId}` |
54+
| [Close the client connection](./swagger/signalr-data-plane-rest-v1.md#close-the-client-connection) | `DELETE /api/v1/hubs/{hub}/connections/{connectionId}` |
55+
| [Broadcast a message to all clients within the target group.](./swagger/signalr-data-plane-rest-v1.md#broadcast-a-message-to-all-clients-within-the-target-group) | `POST /api/v1/hubs/{hub}/groups/{group}` |
56+
| [Check if there are any client connections inside the given group](./swagger/signalr-data-plane-rest-v1.md#check-if-there-are-any-client-connections-inside-the-given-group) | `GET /api/v1/hubs/{hub}/groups/{group}` |
57+
| [Check if there are any client connections connected for the given user](./swagger/signalr-data-plane-rest-v1.md#check-if-there-are-any-client-connections-connected-for-the-given-user) | `GET /api/v1/hubs/{hub}/users/{user}` |
58+
| [Add a connection to the target group.](./swagger/signalr-data-plane-rest-v1.md#add-a-connection-to-the-target-group) | `PUT /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}` |
59+
| [Remove a connection from the target group.](./swagger/signalr-data-plane-rest-v1.md#remove-a-connection-from-the-target-group) | `DELETE /api/v1/hubs/{hub}/groups/{group}/connections/{connectionId}` |
60+
| [Check whether a user exists in the target group.](./swagger/signalr-data-plane-rest-v1.md#check-whether-a-user-exists-in-the-target-group) | `GET /api/v1/hubs/{hub}/groups/{group}/users/{user}` |
61+
| [Add a user to the target group.](./swagger/signalr-data-plane-rest-v1.md#add-a-user-to-the-target-group) | `PUT /api/v1/hubs/{hub}/groups/{group}/users/{user}` |
62+
| [Remove a user from the target group.](./swagger/signalr-data-plane-rest-v1.md#remove-a-user-from-the-target-group) | `DELETE /api/v1/hubs/{hub}/groups/{group}/users/{user}` |
63+
| [Remove a user from all groups.](./swagger/signalr-data-plane-rest-v1.md#remove-a-user-from-all-groups) | `DELETE /api/v1/hubs/{hub}/users/{user}/groups` |
64+
65+
## Using REST API
66+
67+
### Authenticate via Azure SignalR Service AccessKey
68+
69+
In each HTTP request, an authorization header with a [JSON Web Token (JWT)](https://en.wikipedia.org/wiki/JSON_Web_Token) is required to authenticate with SignalR Service.
70+
71+
#### Signing Algorithm and Signature
72+
73+
`HS256`, namely HMAC-SHA256, is used as the signing algorithm.
74+
75+
Use the `AccessKey` in Azure SignalR Service instance's connection string to sign the generated JWT token.
76+
77+
#### Claims
78+
79+
The following claims are required to be included in the JWT token.
80+
81+
Claim Type | Is Required | Description
82+
---|---|---
83+
`aud` | true | Needs to be the same as your HTTP request url, trailing slash and query parameters not included. For example, a broadcast request's audience should look like: `https://example.service.signalr.net/api/v1/hubs/myhub`.
84+
`exp` | true | Epoch time when this token expires.
85+
86+
### Authenticate via Azure Active Directory Token (Azure AD Token)
87+
88+
Similar to authenticating using `AccessKey`, when authenticating using Azure AD Token, a [JSON Web Token (JWT)](https://en.wikipedia.org/wiki/JSON_Web_Token) is also required to authenticate the HTTP request.
89+
90+
The difference is, in this scenario the JWT Token is generated by Azure Active Directory.
91+
92+
[Learn how to generate Azure AD Tokens](/azure/active-directory/develop/reference-v2-libraries)
93+
94+
You could also use **Role Based Access Control (RBAC)** to authorize the request from your client/server to SignalR Service.
95+
96+
[Learn how to configure Role-based access control roles for your resource](/azure/azure-signalr/authorize-access-azure-active-directory)
97+
98+
### Implement Negotiate Endpoint
99+
100+
As shown in the [architecture section](#serverless), you should implement a `negotiate` function that returns a redirect negotiation response so that client can connect to the service.
101+
A typical negotiation response looks as follows:
102+
103+
```json
104+
{
105+
"url":"https://<service_name>.service.signalr.net/client/?hub=<hub_name>",
106+
"accessToken":"<a typical JWT token>"
107+
}
108+
```
109+
110+
The `accessToken` is generated using the same algorithm described in [authentication section](#authenticate-via-azure-signalr-service-accesskey). The only difference is the `aud` claim should be same as `url`.
111+
112+
You should host your negotiate API in `https://<hub_url>/negotiate` so you can still use SignalR client to connect to the hub url.
113+
114+
Read more about redirecting client to Azure SignalR Service at [here](./signalr-concept-internals.md#client-connections).
115+
116+
### User-related REST API
117+
118+
In order to call user-related REST API, each of your clients should identify itself to SignalR Service.
119+
Otherwise SignalR Service can't find target connections from a given user ID.
120+
121+
Client identification can be achieved by including a `nameid` claim in each client's JWT token when they're connecting to SignalR Service.
122+
Then SignalR Service will use the value of `nameid` claim as the user ID of each client connection.
123+
124+
### Sample
125+
126+
You can find a complete console app to demonstrate how to manually build a REST API HTTP request in SignalR Service [here](https://github.com/aspnet/AzureSignalR-samples/tree/master/samples/Serverless).
127+
128+
You can also use [Microsoft.Azure.SignalR.Management](<https://www.nuget.org/packages/Microsoft.Azure.SignalR.Management>) to publish messages to SignalR Service using the similar interfaces of `IHubContext`. Samples can be found [here](<https://github.com/aspnet/AzureSignalR-samples/tree/master/samples/Management>). For more information, see [How to use Management SDK](https://github.com/Azure/azure-signalr/blob/dev/docs/management-sdk-guide.md).
129+
130+
131+
## Limitation
132+
133+
Currently, we have the following limitation for REST API requests:
134+
135+
* Header size is a maximum of 16 KB.
136+
* Body size is a maximum of 1 MB.
137+
138+
If you want to send message larger than 1 MB, use the Management SDK with `persistent` mode.

‎articles/azure-signalr/swagger/signalr-data-plane-rest-v1-preview.md

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
title: Azure SignalR service data plane REST API reference - v1-preview
3+
description: Describes REST APIs version v1-preview Azure SignalR service supports to manage the connections and send messages to them.
4+
author: vicancy
5+
ms.author: lianwei
6+
ms.service: signalr
7+
ms.topic: reference
8+
ms.date: 06/09/2022
9+
---
10+
11+
# Azure SignalR Service data plane REST API - v1-preview
12+
13+
This article contains the obsoleted v1-preview version REST APIs for Azure SignalR Service data plane. Please use the [latest version](./signalr-data-plane-rest-v1.md) instead.
14+
15+
## Available APIs
16+
17+
| API | Path |
18+
| ---- | ---------- |
19+
| [post /api/v1-preview/hub/{hub}/user/{id}](#post-apiv1-previewhubhubuserid) | `POST /api/v1-preview/hub/{hub}/user/{id}` |
20+
| [post /api/v1-preview/hub/{hub}/users/{userList}](#post-apiv1-previewhubhubusersuserlist) | `POST /api/v1-preview/hub/{hub}/users/{userList}` |
21+
| [post /api/v1-preview/hub/{hub}](#post-apiv1-previewhubhub) | `POST /api/v1-preview/hub/{hub}` |
22+
| [post /api/v1-preview/hub/{hub}/group/{group}](#post-apiv1-previewhubhubgroupgroup) | `POST /api/v1-preview/hub/{hub}/group/{group}` |
23+
| [post /api/v1-preview/hub/{hub}/groups/{groupList}](#post-apiv1-previewhubhubgroupsgrouplist) | `POST /api/v1-preview/hub/{hub}/groups/{groupList}` |
24+
25+
### post /api/v1-preview/hub/{hub}/user/{id}
26+
27+
`POST /api/v1-preview/hub/{hub}/user/{id}`
28+
##### Description:
29+
30+
Send a message to a single user.
31+
32+
##### Parameters
33+
34+
| Name | Located in | Description | Required | Schema |
35+
| ---- | ---------- | ----------- | -------- | ---- |
36+
| hub | path | Target hub name, which should start with alphabetic characters and only contain alpha-numeric characters or underscore. | Yes | string |
37+
| id | path | Target user Id. | Yes | string |
38+
| message | body | | Yes | [Message](#message) |
39+
40+
##### Responses
41+
42+
| Code | Description |
43+
| ---- | ----------- |
44+
| 202 | Accepted |
45+
46+
### post /api/v1-preview/hub/{hub}/users/{userList}
47+
48+
`POST /api/v1-preview/hub/{hub}/users/{userList}`
49+
##### Description:
50+
51+
Send a message to multiple users.
52+
53+
##### Parameters
54+
55+
| Name | Located in | Description | Required | Schema |
56+
| ---- | ---------- | ----------- | -------- | ---- |
57+
| hub | path | Target hub name, which should start with alphabetic characters and only contain alpha-numeric characters or underscore. | Yes | string |
58+
| userList | path | Comma-separated list of user Ids. | Yes | string |
59+
| message | body | | Yes | [Message](#message) |
60+
61+
##### Responses
62+
63+
| Code | Description |
64+
| ---- | ----------- |
65+
| 202 | Accepted |
66+
67+
### post /api/v1-preview/hub/{hub}
68+
69+
`POST /api/v1-preview/hub/{hub}`
70+
##### Description:
71+
72+
Broadcast a message to all clients connected to target hub.
73+
74+
##### Parameters
75+
76+
| Name | Located in | Description | Required | Schema |
77+
| ---- | ---------- | ----------- | -------- | ---- |
78+
| hub | path | Target hub name, which should start with alphabetic characters and only contain alpha-numeric characters or underscore. | Yes | string |
79+
| message | body | | Yes | [Message](#message) |
80+
81+
##### Responses
82+
83+
| Code | Description |
84+
| ---- | ----------- |
85+
| 202 | Accepted |
86+
87+
### post /api/v1-preview/hub/{hub}/group/{group}
88+
89+
`POST /api/v1-preview/hub/{hub}/group/{group}`
90+
##### Description:
91+
92+
Broadcast a message to all clients within the target group.
93+
94+
##### Parameters
95+
96+
| Name | Located in | Description | Required | Schema |
97+
| ---- | ---------- | ----------- | -------- | ---- |
98+
| hub | path | Target hub name, which must start with alphabetic characters and contain only alpha-numeric characters or underscore. | Yes | string |
99+
| group | path | Target group name, which must start with alphabetic characters and contain only alpha-numeric characters or underscore. | Yes | string |
100+
| message | body | | Yes | [Message](#message) |
101+
102+
##### Responses
103+
104+
| Code | Description |
105+
| ---- | ----------- |
106+
| 202 | Accepted |
107+
108+
### post /api/v1-preview/hub/{hub}/groups/{groupList}
109+
110+
`POST /api/v1-preview/hub/{hub}/groups/{groupList}`
111+
##### Description:
112+
113+
Broadcast a message to all clients within the target groups.
114+
115+
##### Parameters
116+
117+
| Name | Located in | Description | Required | Schema |
118+
| ---- | ---------- | ----------- | -------- | ---- |
119+
| hub | path | Target hub name, which must start with alphabetic characters and only contain alpha-numeric characters or underscore. | Yes | string |
120+
| groupList | path | Comma-separated list of group names. Each group name must start with alphabetic characters and only contain alpha-numeric characters or underscore. | Yes | string |
121+
| message | body | | Yes | [Message](#message) |
122+
123+
##### Responses
124+
125+
| Code | Description |
126+
| ---- | ----------- |
127+
| 202 | Accepted |
128+
129+
### Models
130+
131+
132+
#### Message
133+
134+
Method invocation message.
135+
136+
| Name | Type | Description | Required |
137+
| ---- | ---- | ----------- | -------- |
138+
| target | string | Target method name. | No |
139+
| arguments | [ object ] | Target method arguments. | No |

0 commit comments

Comments
 (0)