microsoft/teams.net
Publicmirrored fromhttps://github.com/microsoft/teams.netAvailable
core/docs/CompatTeamsInfo-API-Mapping.md
161lines · modecode
| 1 | # TeamsApiClient API Mapping |
| 2 | |
| 3 | This document provides a comprehensive mapping of Bot Framework TeamsInfo static methods to their corresponding REST API endpoints and the Teams Bot Core SDK client implementations. |
| 4 | |
| 5 | ## Overview |
| 6 | |
| 7 | The `TeamsApiClient` class provides a compatibility layer that adapts the Bot Framework v4 SDK TeamsInfo API to use the Teams Bot Core SDK. It maps 19 static methods organized into four functional categories. |
| 8 | |
| 9 | ## API Method Mappings |
| 10 | |
| 11 | ### Member & Participant Methods |
| 12 | |
| 13 | | Method | REST Endpoint | Client | Status | |
| 14 | |--------|--------------|--------|--------| |
| 15 | | `GetMemberAsync` | `GET /v3/conversations/{conversationId}/members/{userId}` | ConversationClient | Implemented | |
| 16 | | `GetMembersAsync` | `GET /v3/conversations/{conversationId}/members` | ConversationClient | Implemented (deprecated) | |
| 17 | | `GetPagedMembersAsync` | `GET /v3/conversations/{conversationId}/pagedmembers?pageSize=&continuationToken=` | ConversationClient | Implemented | |
| 18 | | `GetTeamMemberAsync` | `GET /v3/conversations/{teamId}/members/{userId}` | ConversationClient | Implemented | |
| 19 | | `GetTeamMembersAsync` | `GET /v3/conversations/{teamId}/members` | ConversationClient | Implemented (deprecated) | |
| 20 | | `GetPagedTeamMembersAsync` | `GET /v3/conversations/{teamId}/pagedmembers?pageSize=&continuationToken=` | ConversationClient | Implemented | |
| 21 | |
| 22 | > `GetMembersAsync` and `GetTeamMembersAsync` are deprecated by Microsoft Teams. Use paged versions instead. |
| 23 | |
| 24 | ### Meeting Methods |
| 25 | |
| 26 | | Method | REST Endpoint | Client | Status | |
| 27 | |--------|--------------|--------|--------| |
| 28 | | `GetMeetingInfoAsync` | `GET /v1/meetings/{meetingId}` | ApiClient.Meetings | Implemented | |
| 29 | | `GetMeetingParticipantAsync` | `GET /v1/meetings/{meetingId}/participants/{participantId}?tenantId={tenantId}` | ApiClient.Meetings | Implemented | |
| 30 | | `SendMeetingNotificationAsync` | `POST /v1/meetings/{meetingId}/notification` | — | Commented out (needs `MeetingClient.SendMeetingNotificationAsync`) | |
| 31 | |
| 32 | > `GetMeetingParticipantAsync` requires an AAD object ID for `participantId`, not a Bot Framework MRI or pairwise ID. |
| 33 | |
| 34 | ### Team & Channel Methods |
| 35 | |
| 36 | | Method | REST Endpoint | Client | Status | |
| 37 | |--------|--------------|--------|--------| |
| 38 | | `GetTeamDetailsAsync` | `GET /v3/teams/{teamId}` | ApiClient.Teams | Implemented — uses `client.Teams.GetByIdAsync()` | |
| 39 | | `GetTeamChannelsAsync` | `GET /v3/teams/{teamId}/conversations` | ApiClient.Teams | Implemented — uses `client.Teams.GetConversationsAsync()` | |
| 40 | |
| 41 | ### Batch Messaging Methods |
| 42 | |
| 43 | | Method | REST Endpoint | Client | Status | |
| 44 | |--------|--------------|--------|--------| |
| 45 | | `SendMessageToListOfUsersAsync` | `POST /v3/batch/conversation/users/` | — | Commented out (needs BatchClient) | |
| 46 | | `SendMessageToListOfChannelsAsync` | `POST /v3/batch/conversation/channels/` | — | Commented out (needs BatchClient) | |
| 47 | | `SendMessageToAllUsersInTeamAsync` | `POST /v3/batch/conversation/team/` | — | Commented out (needs BatchClient) | |
| 48 | | `SendMessageToAllUsersInTenantAsync` | `POST /v3/batch/conversation/tenant/` | — | Commented out (needs BatchClient) | |
| 49 | | `SendMessageToTeamsChannelAsync` | Uses Bot Framework Adapter | BotAdapter.CreateConversationAsync | Implemented | |
| 50 | |
| 51 | ### Batch Operation Management Methods |
| 52 | |
| 53 | | Method | REST Endpoint | Client | Status | |
| 54 | |--------|--------------|--------|--------| |
| 55 | | `GetOperationStateAsync` | `GET /v3/batch/conversation/{operationId}` | — | Commented out (needs BatchClient) | |
| 56 | | `GetPagedFailedEntriesAsync` | `GET /v3/batch/conversation/failedentries/{operationId}?continuationToken=` | — | Commented out (needs BatchClient) | |
| 57 | | `CancelOperationAsync` | `DELETE /v3/batch/conversation/{operationId}` | — | Commented out (needs BatchClient) | |
| 58 | |
| 59 | ## Client Distribution |
| 60 | |
| 61 | ### ConversationClient (6 methods) — Implemented |
| 62 | |
| 63 | Used for member and participant operations in conversations and teams. Accessed via the `CompatConnectorClient` in TurnState (`turnContext.TurnState.Get<IConnectorClient>()` → cast to `CompatConnectorClient` → `CompatConversations._client`). |
| 64 | |
| 65 | - GetMemberAsync |
| 66 | - GetMembersAsync |
| 67 | - GetPagedMembersAsync |
| 68 | - GetTeamMemberAsync |
| 69 | - GetTeamMembersAsync |
| 70 | - GetPagedTeamMembersAsync |
| 71 | |
| 72 | ### ApiClient sub-clients (4 methods) — Implemented |
| 73 | |
| 74 | `ApiClient` is stored in TurnState by `TeamsBotFrameworkHttpAdapter`. Must be scoped to serviceUrl via `ForServiceUrl()` before use. Uses sub-clients: |
| 75 | |
| 76 | - `ApiClient.Meetings.GetByIdAsync()` — GetMeetingInfoAsync |
| 77 | - `ApiClient.Meetings.GetParticipantAsync()` — GetMeetingParticipantAsync |
| 78 | - `ApiClient.Teams.GetByIdAsync()` — GetTeamDetailsAsync |
| 79 | - `ApiClient.Teams.GetConversationsAsync()` — GetTeamChannelsAsync |
| 80 | |
| 81 | ### Bot Framework Adapter (1 method) — Implemented |
| 82 | |
| 83 | - SendMessageToTeamsChannelAsync — uses `turnContext.Adapter.CreateConversationAsync()` |
| 84 | |
| 85 | ### Not yet implemented (8 methods) — Commented out |
| 86 | |
| 87 | These methods are commented out in `TeamsApiClient` pending new client support: |
| 88 | |
| 89 | - SendMeetingNotificationAsync — needs `MeetingClient.SendMeetingNotificationAsync` |
| 90 | - SendMessageToListOfUsersAsync — needs BatchClient |
| 91 | - SendMessageToListOfChannelsAsync — needs BatchClient |
| 92 | - SendMessageToAllUsersInTeamAsync — needs BatchClient |
| 93 | - SendMessageToAllUsersInTenantAsync — needs BatchClient |
| 94 | - GetOperationStateAsync — needs BatchClient |
| 95 | - GetPagedFailedEntriesAsync — needs BatchClient |
| 96 | - CancelOperationAsync — needs BatchClient |
| 97 | |
| 98 | ## Migration Checklist |
| 99 | |
| 100 | | Item | Status | |
| 101 | |---|---| |
| 102 | | Member operations via ConversationClient | Done | |
| 103 | | Meeting info via ApiClient.Meetings | Done | |
| 104 | | Meeting participant via ApiClient.Meetings | Done | |
| 105 | | Team details via ApiClient.Teams | Done | |
| 106 | | Team channels via ApiClient.Teams | Done | |
| 107 | | SendMessageToTeamsChannelAsync via adapter | Done | |
| 108 | | Batch messaging (4 methods) | Needs BatchClient on ApiClient | |
| 109 | | Batch operations (3 methods) | Needs BatchClient on ApiClient | |
| 110 | | Meeting notifications | Needs MeetingClient.SendMeetingNotificationAsync | |
| 111 | | TeamsBotFrameworkHttpAdapter scopes ApiClient per-request | Needs update to call ForServiceUrl | |
| 112 | |
| 113 | ## Type Conversions |
| 114 | |
| 115 | Key extension methods in `ActivitySchemaMapper.cs` and `TeamsApiClient.Models.cs`: |
| 116 | |
| 117 | | Extension Method | Source Type | Target Type | Used By | Status | |
| 118 | |---|---|---|---|---| |
| 119 | | `ToCompatTeamsChannelAccount` | `ConversationAccount` | BF `TeamsChannelAccount` | GetMember/GetMembers/GetTeamMember/GetTeamMembers | Working | |
| 120 | | `ToCompatTeamsPagedMembersResult` | `PagedMembersResult` | BF `TeamsPagedMembersResult` | GetPagedMembers/GetPagedTeamMembers | Working | |
| 121 | | `ToCompatChannelInfo` | `TeamsChannel` | BF `ChannelInfo` | GetTeamChannelsAsync | Working | |
| 122 | | `ToCompatTeamDetails` | `Apps.Schema.Team` | BF `TeamDetails` | Defined but unused — GetTeamDetailsAsync uses inline mapping | Available | |
| 123 | | `ToCompatTeamsMeetingParticipant` | `MeetingParticipant` | BF `TeamsMeetingParticipant` | Defined but unused — GetMeetingParticipantAsync uses inline mapping | Available | |
| 124 | | `ToCompatBatchOperationState` | `BatchOperationState` | BF `BatchOperationState` | — | Commented out (needs models) | |
| 125 | | `ToCompatBatchFailedEntriesResponse` | `BatchFailedEntriesResponse` | BF `BatchFailedEntriesResponse` | — | Commented out (needs models) | |
| 126 | | `ToCompatMeetingNotificationResponse` | `MeetingNotificationResponse` | BF `MeetingNotificationResponse` | — | Commented out (needs models) | |
| 127 | | `FromCompatTeamMember` | BF `TeamMember` | `Apps.TeamMember` | — | Commented out (needs models) | |
| 128 | |
| 129 | ## Authentication |
| 130 | |
| 131 | All methods use `AgenticIdentity` extracted from the turn context activity properties for authentication with the Teams services. The identity is obtained by converting the Bot Framework `Activity` to a `CoreActivity` and extracting agentic properties from `From.Properties`. |
| 132 | |
| 133 | ## Service URL |
| 134 | |
| 135 | All API calls use the service URL from the turn context activity (`turnContext.Activity.ServiceUrl`): |
| 136 | |
| 137 | - **ConversationClient** methods receive `serviceUrl` as a `Uri` parameter directly |
| 138 | - **ApiClient** sub-client methods use the serviceUrl baked into the scoped client instance |
| 139 | |
| 140 | The `TeamsBotFrameworkHttpAdapter` must store a **scoped** `ApiClient` in TurnState for Teams/Meetings sub-clients to work. Currently it stores the unscoped base instance — this is a known pending fix (see [ApiClient Design](ApiClient-Design.md#integration-with-compatteamsinfo)). |
| 141 | |
| 142 | ## Testing |
| 143 | |
| 144 | Integration tests are available in `core/test/IntegrationTests/`: |
| 145 | |
| 146 | | Test File | Coverage | |
| 147 | |---|---| |
| 148 | | `TeamsApiClientTests.cs` | 14 tests covering all implemented TeamsApiClient methods via real API calls with a simulated TurnContext | |
| 149 | | `ApiClientTests.cs` | Direct tests for ApiClient sub-clients (Activities, Members, Teams, Meetings, UserToken, BotSignIn) | |
| 150 | | `ConversationClientTests.cs` | Core ConversationClient operations | |
| 151 | | `CreateConversationTests.cs` | Conversation creation patterns | |
| 152 | |
| 153 | Tests require the `integration.runsettings` file with environment variables: |
| 154 | - `TEST_USER_ID`, `TEST_CONVERSATIONID`, `TEST_TEAMID`, `TEST_CHANNELID`, `TEST_MEETINGID`, `TEST_TENANTID` |
| 155 | - Azure AD credentials (`AzureAd__TenantId`, `AzureAd__ClientId`, `AzureAd__ClientSecret`) |
| 156 | |
| 157 | ## References |
| 158 | |
| 159 | - [ApiClient Design Document](ApiClient-Design.md) — Architecture, delegation patterns, and scoping |
| 160 | - [CreateConversation API Behavior](CreateConversation-API-Behavior.md) — Detailed API behavior with request/response examples |
| 161 | - [Bot Framework TeamsInfo Source](https://github.com/microsoft/botbuilder-dotnet/blob/main/libraries/Microsoft.Bot.Builder/Teams/TeamsInfo.cs) |