使用 Microsoft Teams 匯出 API 匯出內容
Teams 匯出 API 可讓您從 Teams 匯出 1:1、群組聊天、會議聊天和頻道訊息Microsoft。 如果您的組織需要匯出 Microsoft Teams 訊息,您可以使用 Teams 匯出 API 來解壓縮它們。 聊天訊息 代表 頻道 或聊天中的個別 聊天訊息。 聊天訊息可以是根聊天訊息或由聊天訊息中的 replyToId 屬性定義的回復對話的一部分。
以下是一些您可以如何使用這些匯出 API 的範例:
範例 1:如果您已啟用組織中的 Microsoft Teams,並想要透過傳遞指定使用者或團隊的日期範圍,以程式設計方式將所有Microsoft Teams 訊息導出至日期。
範例 2:如果您想要提供日期範圍,以程式設計方式每天匯出所有使用者或小組訊息。 匯出 API 可以擷取在指定日期範圍內建立或更新的所有郵件。
範例 3:如果您想要以程式設計方式匯出指定會議召集人的 Teams 會議錄製連結,然後下載實際的錄製。
範例 4:如果您想要以程式設計方式匯出指定會議召集人的 Teams 會議文字記錄連結,然後下載實際的文字記錄。
Teams 匯出 API 支援哪些功能?
大量導出Teams訊息: Teams 匯出 API 支援最多 200 個每個 App 每個租使用者 200 RPS,以及 600 個應用程式 RPS,在這些限制下,您應該能夠大量匯出 Teams 訊息。
應用程式內容:若要呼叫 Microsoft Graph,您的應用程式必須從 Microsoft 身分識別平台 取得存取令牌。 存取令牌包含應用程式的相關信息,以及它對於可透過 Microsoft Graph 取得之資源和 API 的許可權。 若要取得存取令牌,您的應用程式必須向 Microsoft 身分識別平台 註冊,並獲得使用者或系統管理員的授權,以存取所需的 Microsoft Graph 資源。
如果您已經熟悉將應用程式與 Microsoft 身分識別平台 整合以取得令牌,請參閱一節以取得圖形Microsoft專屬的資訊和範例。
混合式環境: 匯出由在混合式環境 (內部部署 Exchange 和 Teams) 布建的使用者所傳送的支援訊息。 任何由設定混合式環境的使用者所傳送的郵件,都可使用匯出API存取。
使用者刪除的郵件: 使用者從 Teams 用戶端刪除的訊息,最多可在刪除後 21 天內使用匯出 API 存取。
郵件附件: 匯出 API 包含郵件中傳送附件的連結。 您可以使用 [匯出 API] 擷取郵件中附加的檔案。
反應: 匯出由使用者在 Teams 訊息上啟動的 API 支持反應。 目前支援的圖釋有心、生氣、讚、傷心、驚訝和大笑。 除了反應之外,導出API也支援 [反應編輯歷程記錄],其中包含對郵件上回應所做的變更和更新。
共用頻道訊息: 匯出 API 支援從共用通道擷取訊息。
已刪除Teams: 匯出 API 支援 從已刪除的 Teams 擷取訊息 ,以及刪除的標準、私人和共用頻道。
已刪除的用戶:匯出 API 支援從刪除使用者起 30 天內擷取已刪除使用者的訊息。 若要尋找已刪除的使用者清單,請參閱 刪除的郵件。
聊天訊息內容: 請參閱 Teams匯出 API 支援的完整屬性清單。
控制訊息: 匯出 API 除了用戶產生的訊息外,還支援擷取控制訊息。 [控制訊息] 是系統產生的訊息,會顯示在 Teams 用戶端上,並帶有重要資訊,例如「使用者 A 已新增使用者 B 至聊天,並共用所有聊天記錄」以及時間戳。 系統訊息可讓來電者深入瞭解團隊、頻道或聊天中發生的事件。 請參閱匯出 API 目前支援的 控制措施訊息清單 。
注意事項
匯出 API 目前不支援會議相關控制訊息。
編輯的歷程記錄: 如果您的 租用戶已設定 Teams 保留原則,匯出 API 支援擷取 個別 & 群組聊天的訊息編輯歷程記錄,以及 公開 & 共用頻道中的貼文和留言。
若要深入瞭解 Teams 保留原則,請參閱 管理 Microsoft Teams 的保留原則 以取得進一步的詳細數據。
如何存取Teams匯出 API
範例 1 是一個簡單的查詢,可擷取使用者或小組的所有訊息,而不需要任何篩選:
GET https://graph.microsoft.com/v1.0/users/{id}/chats/getAllMessages
GET https://graph.microsoft.com/v1.0/teams/{id}/channels/getAllMessages
範例 2 是範例查詢,藉由指定日期時間篩選器和前 50 封郵件來擷取使用者或小組的所有郵件:
GET https://graph.microsoft.com/v1.0/users/{id}/chats/getAllMessages?$top=50&$filter=lastModifiedDateTime gt 2020-06-04T18:03:11.591Z and lastModifiedDateTime lt 2020-06-05T21:00:09.413Z
GET https://graph.microsoft.com/v1.0/teams/{id}/channels/getAllMessages?$top=50&$filter=lastModifiedDateTime gt 2020-06-04T18:03:11.591Z and lastModifiedDateTime lt 2020-06-05T21:00:09.413Z
範例 3 是可擷取使用者所有可用 Teams 會議錄製內容之連結的範例查詢。 支援日期範圍篩選。 支援 TOP n 篩選類似於聊天訊息:
GET https://graph.microsoft.com/v1.0/users/{id}/onlineMeetings/getAllRecordings?$filter=MeetingOrganizer/User/Id eq ‘{id}’
GET https://graph.microsoft.com/v1.0/users/{id}/onlineMeetings/getAllRecordings(meetingOrganizerUserId='{userId}',startDateTime={startDateTime},endDateTime={endDateTime})
範例 4 是一個範例查詢,用於擷取使用者所有可用 Teams 會議文字記錄的連結。 支援日期範圍篩選。 支援 TOP n 篩選類似於聊天訊息:
GET https://graph.microsoft.com/v1.0/users/{id}/onlineMeetings/getAllTranscripts?$filter=MeetingOrganizer/User/Id eq ‘{id}’
GET https://graph.microsoft.com/v1.0/users/{id}/onlineMeetings/getAllTranscripts(meetingOrganizerUserId='{userId}',startDateTime={startDateTime},endDateTime={endDateTime})
注意事項
如果出現多個結果,API 會傳回具有下一頁連結的回應。 若要取得下一組結果,只要從中撥打 GET URL @odata.nextlink即可。 如果沒有 @odata.nextlink 出現或 Null,則會擷取所有郵件。
注意事項
回應中的郵件順序不保證會依據任何日期時間排序,例如 createdDateTime 或 lastModifiedDateTime。
存取Teams匯出API的先決條件
Microsoft在 Microsoft Graph 中存取機密數據的 Teams API 被視為受保護的 API。 只要符合 無使用者存取 的需求,您就可以呼叫這些 API。
應用程式許可權的使用方式是非登入使用者出席的情況下執行的應用程式;應用程式許可權只能由系統管理員核准。 需要下列權限:
Chat.Read.All:啟用所有 1:1、群組聊天和會議聊天訊息的存取權
ChannelMessage.Read.All:啟用所有頻道訊息的存取權
User.Read.All:啟用對租用戶使用者清單的存取權
OnlineMeetingTranscript.Read.All:啟用所有 1:n 已排程 Teams 會議的文字記錄存取權
OnlineMeetingRecording.Read.All:可存取所有 1:n 排程 Teams 會議的錄製內容
Teams 匯出 API 的授權需求
匯出 API 透過模型查詢參數支援安全性與合規性 (S+C) 和一般使用情境。 S+C 案例 (型號 A) 包含種子容量,並且需要 E5 訂閱和一般使用案例, (模型 B) 適用於所有訂閱,且僅供使用。 如需有關種子容量和消費費用的詳細資訊,請參閱 Microsoft Graph Teams API 的授權與付款需求。
針對 Beta API,目前沒有模型 A 或模型 B 授權或使用強制執行。 不過,未來可能會有所變更。
S+C/模型 A 案例
受限於執行安全性和/或合規性功能的應用程式,用戶必須擁有特定的 E5 授權,才能使用此功能並獲得種子容量。 種子容量是每個使用者,每月計算,並根據租用戶層級匯總。 對於超出種子容量的使用量,系統會向應用程式擁有者收取API使用量費用。 型號 A 只能存取來自已指派 E5 授權的使用者的訊息。
合作夥伴名稱 | 合作夥伴解決方案 |
---|---|
Microsoft Teams 封存與合規性 | |
Microsoft Teams 的校訂點內容擷取 |
一般使用量/B 模型案例
適用於所有非 S+C 相關案例,沒有授權需求或種子容量。 當可用的消費計量表時,系統會針對所有每月 API 通話向應用程式擁有者收費。
下列合作夥伴已通過認證。 貴公司可選擇與企業內的這些合作夥伴合作。
合作夥伴名稱 | 合作夥伴解決方案 |
---|---|
Microsoft Teams 備份與復原 | |
Microsoft Teams 備份與復原 |
後續步驟
如果您是尋求加入認證計劃的廠商,請填寫 此窗體 做為下一個步驟。 如果您需要提供更多內容和詳細數據,請郵寄至 MS Teams 生態系統小組 (TeamsCategoryPartner@microsoft.com) 。
評估模式 (預設)
任何模型宣告都無法針對每個要求的應用程式針對評估目的限制使用 API。
JSON 表示
下列範例是聊天資源的 JSON 表示:
命名空間:microsoft.graph
{ "id": "string (identifier)", "replyToId": "string (identifier)", "from": {"@odata.type": "microsoft.graph.identitySet"}, "etag": "string", "messageType": "string", "createdDateTime": "string (timestamp)", "lastModifiedDateTime": "string (timestamp)", "deletedDateTime": "string (timestamp)", "subject": "string", "from": { "application": null, "device": null, "conversation": null, "user": { "id": \[{"@odata.type": "microsoft.graph.user"}\], "displayName": "User Name", "userIdentityType": "aadUser" } }, "body": {"@odata.type": "microsoft.graph.itemBody"}, "summary": "string", "chatId": \[{"@odata.type": "microsoft.graph.chat"}\] "attachments": \[{"@odata.type": "microsoft.graph.chatMessageAttachment"}\], "mentions": \[{"@odata.type": "microsoft.graph.chatMessageMention"}\], "importance": "string", "locale": "string", }
注意事項
如需有關 chatMessage 資源的詳細資訊,請參閱 chatMessage 資源類型 文章。
下列範例是記錄資源的 JSON 表示:
命名空間:microsoft.graph
{ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(meetingRecording)", "@odata.count": 2, "@odata.nextLink": "https://graph.microsoft.com/v1.0/users('{userId}')/onlineMeetings/getAllRecordings?$filter=MeetingOrganizer%2fUser%2fId+eq+%27{userId}%27&$skiptoken=MSMjMCMjTkNaYVNIQjVVbXRPYWxaV1dscGFWVGg1V2pOb1IxUXpRWGxrUm1oTFVrWmtTV1ZyYkhwUlZVWm9UMWR3VEdWWGRFTlJWVVpDVVZFOVBRPT0%3d", "value": [ { "@odata.type": "#microsoft.graph.meetingRecording", "id": "6263af16-b660-41d0-a17b-83fbd15a39c7", "meetingId": "MSoxMjczYTAxNi0yMDFkRLTmOTUtODA5My0xYjdmOTliM2VkZWIqMCoqMTk6bWVldGluZ19aR1F3WTJZNE9XTXROekppWlMwME1XWTRMVGc0TWpBdE1BBXdOV1kzWlRsak9UTXlAdGhyZWFkLnYy", "meetingOrganizerId": "{userId}", "createdDateTime": "2022-08-03T20:43:36.2573447Z", "recordingContentUrl": "https://graph.microsoft.com/v1.0/users/{userId}/onlineMeetings/MSoxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWIqMCoqMTk6bWVldGluZ19aR1F3WTJZNE9XTXROekppWlMwME1XWTRMVGc0TWpBdE1ERXdOV1kzWlRsak9UTXlAdGhyZWFkLnYy/recordings/MSMjMCMjMGFjNmUwZTgtYmZjYy00NDQxLTk2MGYtZjllNjVhNjI0NzBh/content" }, { "@odata.type": "#microsoft.graph.meetingRecording", "id": "{recordingId}", "meetingId": "{meetingId}", "meetingOrganizerId": "{userId}", "createdDateTime": "2022-08-03T20:44:11.2635254Z", "recordingContentUrl": " https://graph.microsoft.com/v1.0/users/{userId}/onlineMeetings/{meetingId}/recordings/{recordingId}/content" }, ] }
其中:
<id>
代表單一錄製。<meetingId>
代表會議或通話標識碼。<meetingOrganizer/user/id>
代表會議召集人。<createdDateTime>
表示會議的開始時間。<recordingContentUrl>
值表示錄製內容的 URL。錄製是 MP4 格式。
根據我們在 30 分鐘到 60 分鐘之間開會時所看到的平均值,錄製內容本身的平均大小大約為 350 MB。
結果不保證由排序。
createdDateTime
不過,如果在單一會議中有多個錄製內容,則會共用相同的meetingId
值。 此外,多個錄製專案會針對有問題的會議正確排序。只有在有相關聯的會議錄製內容可用時,結果才可保證顯示。 換句話說,來電者不需要額外輪詢可用性。
在 Teams 匯出 API 中,系統會根據目前的模式支援翻閱結果。 系統會透過回應中包含
@oData.nextLink
屬性來支援Pagination。 NextLink 屬性包含值skipToken
,如下所示。skipToken
如果沒有出現,表示目前批次中不會再擷取結果:請求 回應 @nextLink 註解 /getAllRecordings
計數:10 ?skipToken=ABC
未提出初始要求 skipToken
/getAllRecordings?skipToken=ABC
計數:10 ?skipToken=DEF
SkipToken
已退回,要求取得下一頁/getAllRecordings?skipToken=DEF
計數:7 否 skipToken
,不再提供任何數據$top
在 Teams 匯出 API 中,參數也會根據目前的模式受到支援。DeltaToken
以啟用追蹤修訂和同步處理案例。 如需現有差異查詢的概觀和範例,請參閱 使用差異查詢來追蹤 Microsoft Graph 數據中的變更。下列 API 可用來取得所選
userId
取內容的實際錄製內容,meetingId
並在recordingId
GETgetAllRecordings
API 回應中取得。 它會傳回錄製內容:
GET users('{userId}')/onlineMeetings('{meetingId}')/recordings('{recordingId}')/content
下列範例是文字記錄資源的 JSON 表示:
命名空間:microsoft.graph
{ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(callTranscript)", "@odata.count": 2, "@odata.nextLink": "https://graph.microsoft.com/v1.0/users('{userId}')/onlineMeetings/getAllTranscripts?$filter=MeetingOrganizer%2fUser%2fId+eq+%27{userId}%27&$skiptoken=MSMjMCMjTkNaYVNIQjVVbXRPYWxaV1dscGFWVGg1V2pOb1IxUXpRWGxrUm1oTFVrWmtTV1ZyYkhwUlZVWm9UMWR3VEdWWGRFTlJWVVpDVVZFOVBRPT0%3d", "value": [ { "@odata.type": "#microsoft.graph.callTranscript", "id": "MSMjMCMjMGFjNmUwZTgtYmZjYy00NDQxLTk2MGYtZjllNjVhNjI0NzBh", "meetingId": "MSoxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWIqMCoqMTk6bWVldGluZ19aR1F3WTJZNE9XTXROekppWlMwME1XWTRMVGc0TWpBdE1ERXdOV1kzWlRsak9UTXlAdGhyZWFkLnYy", "meetingOrganizerId": "{userId}", "transcriptContentUrl": "https://graph.microsoft.com/v1.0/users/{userId}/onlineMeetings/MSoxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWIqMCoqMTk6bWVldGluZ19aR1F3WTJZNE9XTXROekppWlMwME1XWTRMVGc0TWpBdE1ERXdOV1kzWlRsak9UTXlAdGhyZWFkLnYy/transcripts/MSMjMCMjMGFjNmUwZTgtYmZjYy00NDQxLTk2MGYtZjllNjVhNjI0NzBh/content", "createdDateTime": "2022-08-03T20:43:36.6248355Z" }, { "@odata.type": "#microsoft.graph.callTranscript", "id": "{transcriptId}", "meetingId": "{meetingId}", "meetingOrganizerId": "{userId}", "transcriptContentUrl": "https://graph.microsoft.com/v1.0/users/{userId}/onlineMeetings/{meetingId}/transcripts/{transcriptId}/content", }, ] }
其中:
<id>
代表單一錄製。<meetingId>
代表會議或通話標識碼。<meetingOrganizer/user/id>
代表會議召集人。<createdDateTime>
表示會議的開始時間。<transcriptContentUrl>
值表示文字記錄內容的 URL。根據預設,文字記錄內容會是 VTT 格式。 但是,您也可以使用 「接受」標題值 ,
application/vnd.openxmlformats-officedocument.wordprocessingml.document
即 DOCX 格式。以 JSON/VTT 格式的文字記錄內容本身的平均大小大約是 300 KB,根據我們在 30 分鐘到 60 分鐘範圍內的會議所看到的平均值。
結果不保證由排序。
createdDateTime
不過,如果在單一會議中有多個錄製內容,則會共用相同的meetingId
值。 此外,多個錄製專案會針對有問題的會議正確排序。只有在有相關聯的會議錄製內容可用時,結果才可保證顯示。 換句話說,來電者不需要額外輪詢可用性。
在 Teams 匯出 API 中,系統會根據目前的模式支援翻閱結果。 系統會透過回應中包含
@oData.nextLink
屬性來支援Pagination。 屬性nextLink
會包含值skipToken
,如下所示。skipToken
如果沒有出現,表示目前批次中不會再擷取結果:請求 回應 @nextLink 註解 /getAllTranscripts
計數:10 ?skipToken=ABC
未提出初始要求 skipToken
/getAllTranscripts?skipToken=ABC
計數:10 ?skipToken=DEF
SkipToken
已退回,要求取得下一頁/getAllTranscripts?skipToken=DEF
計數:7 否 skipToken
,不再提供任何數據$top
在 Teams 匯出 API 中,參數也會根據目前的模式受到支援。DeltaToken
以啟用追蹤修訂和同步處理案例。 如需現有差異查詢的概觀和範例,請參閱 使用差異查詢追蹤 Microsoft圖形數據中的變更下列 API 可用來取得在 GET getAllTranscripts API 回應中取得之所選使用者Id、meetingId 和 transcriptId 的實際文字記錄內容。 它會傳回錄製內容。
GET users('{userId}')/onlineMeetings('{meetingId}')/transcripts('{transcriptId}')/content
如需詳細資訊,請參閱 使用圖形 API 擷取文字記錄。
匯出 API 篩選
在 Teams Graph Service 上託管的匯出 API 會使用 users/{userId}/chats/getAllMessages
從 [基底] 使用者信箱取得所有使用者訊息。 匯出 API 會擷取使用者的已傳送和接收訊息,導致在聊天對話中為所有使用者撥打 API 時匯出重複的訊息。
匯出 API 具有篩選參數,可協助優化傳回聊天對話的訊息。 API GET 支援新的篩選參數,可讓您根據傳送的使用者、Bot、應用程式和系統事件訊息來擷取郵件。 篩選參數支援以下所傳送的郵件:
使用者 (相同要求中支援多個使用者標識碼)
應用程式 (機器人、連接器等 )
匿名使用者
同盟使用者 (外部存取使用者)
系統事件訊息 (控制郵件)
這些參數是要求的一 $filter
部分。 如果這些參數都未出現在要求中,則會傳回在指定的使用者聊天中,來自所有用戶的訊息。
支援的篩選案例如下所示:
$filter=from/application/applicationIdentityType eq '<appType>' (bots/tenantBots/connectors, etc.)
$filter=from/user/id eq '<oid>' (any number of id filters)
$filter=from/user/userIdentityType eq 'anonymousGuest'
$filter=from/user/userIdentityType eq 'federatedUser' (guest/external)
$filter=from/application/applicationIdentityType eq '<appType>' or from/user/id eq '<oid>' (sent by app or userid)
$filter=from/application/applicationIdentityType eq '<appType>' or from/user/userIdentityType eq 'anonymousGuest' (sent by app or anonymous)
$filter=from/application/applicationIdentityType eq '<appType>' or from/user/userIdentityType eq 'federatedUser' (sent by app or federated)
$filter=from/application/applicationIdentityType eq '<appType>' or from/user/userIdentityType eq 'anonymousGuest' or from/user/userIdentityType eq 'federatedUser' (sent by app, anonymous or federated)
$filter=from/user/id eq '<oid>' or from/user/userIdentityType eq 'anonymousGuest' (sent by any number of userid or anonymous)
$filter=from/user/id eq '<oid>' or from/user/userIdentityType eq 'federatedUser' (sent by any number of userid or federated)
$filter=from/application/applicationIdentityType eq '<appType>' or from/user/id eq '<oid>' or from/user/userIdentityType eq 'anonymousGuest' or from/user/userIdentityType eq 'federatedUser' (sent by any number of userid or federated or anonymous)
$filter=from/application/applicationIdentityType eq '<appType>' or from/user/id eq '<oid>' or from/user/userIdentityType eq 'anonymousGuest' or from/user/userIdentityType eq 'federatedUser' (sent by any number of userid or federated or anonymous) or messsageType eq 'systemEventMessage'
(<any of the previous filters>) and (lastModifiedDateTime+gt+<date>+and+lastModifiedDateTime+lt+<date>)
如果
from/user/id eq ‘{oid}’
存在,查詢會傳回指定用戶傳送的訊息。查詢會傳回由同盟使用者傳送且屬於使用者聊天一部分的訊息,如果有
from/user/userIdentityType eq ‘federatedUser’
的話。如果
from/application/applicationIdenitytyType eq '{appType}'
存在,查詢會傳回由指定應用程式類型傳送的郵件。如果
messageType eq 'systemEventMessage'
存在,查詢會傳回由系統傳送的郵件
這些參數可以使用 OR 運算子結合,也可以結合 lastModifiedDateTime
$filter
參數。
Microsoft 365 Copilot (預覽版 & Microsoft 365 Chat 互動)
新的 Copilot 活動匯出 API 可讓您將 Copilot 互動數據匯出,其中包含使用者提示給 Copilot 以及 Copilot 回應回使用者。 此 API 會擷取使用者意圖,以及 Copilot 存取的資源,以及在 Teams、Word 和 Outlook 等 Microsoft 365 Copilot 應用程式中回復給使用者。
如何存取 Copilot 活動匯出 API (預覽)
範例 1 是一個簡單的查詢,可擷取所有副工具互動,而不需要任何篩選 (beta 版) :
GET https://graph.microsoft.com/beta/copilot/users/{id}/interactionHistory/getAllEnterpriseInteractions
範例 2 是一個簡單的查詢,用來擷取所有與 appclass 篩選器的副工具互動, (beta 版) :
GET https://graph.microsoft.com/beta/copilot/users/{id}/interactionHistory/getAllEnterpriseInteractions?$filter=appClass eq 'IPM.SkypeTeams.Message.Copilot.Teams or appClass eq 'IPM.SkypeTeams.Message.Copilot.BizChat' (beta)
存取 Copilot 活動匯出 API (預覽) 的必要條件
應用程式許可權的使用方式是非登入使用者出席的情況下執行的應用程式;應用程式許可權只能由系統管理員核准。 需要下列權限:
- AiEnterpriseInteraction.Read.All:可存取Microsoft 365 應用程式和 Microsoft 365 Chat 的所有副工具互動
- 存取新的 Copilot 活動匯出 API 需要 Microsoft 365 Copilot 授權。