Chuyển tới nội dung chính

Đăng ký ứng dụng Microsoft Graph

Quy trình cuộc họp của Teams đọc bản ghi cuộc họp, bản ghi và các tạo phẩm có liên quan từ Microsoft Graph bằng cách sử dụng xác thực chỉ ứng dụng (daemon) — không cần người dùng đăng nhập, không có sự đồng ý tương tác cho mỗi cuộc họp. Điều đó yêu cầu đăng ký ứng dụng Azure AD với quyền ứng dụng được quản trị viên đồng ý.

Hướng dẫn này đi qua:

  1. Tạo đăng ký ứng dụng
  2. Tạo bí mật khách hàng
  3. Cấp quyền API Đồ thị mà quy trình cần
  4. Sự đồng ý của quản trị viên về các quyền đó
  5. (Tùy chọn) Xác định phạm vi ứng dụng cho những người dùng cụ thể bằng Chính sách truy cập ứng dụng

Bạn cần quyền quản trị viên của đối tượng (hoặc quản trị viên thay mặt bạn cấp sự đồng ý) để hoàn tất việc này. Đánh dấu các giá trị bạn thu thập - chúng sẽ được nhập vào

~/.Hermes/.env ` ở cuối.

Điều kiện tiên quyết​

  • Người thuê Microsoft 365 có giấy phép Teams Premium hoặc Teams để tạo bản ghi và bản ghi cuộc họp
  • Quyền truy cập của quản trị viên vào cổng Azure tại entra.Microsoft.com
  • Điểm cuối HTTPS có thể truy cập công khai dành cho thông báo thay đổi Biểu đồ (được thiết lập sau, trong bước trình nghe webhook)

Bước 1: Tạo Đăng ký ứng dụng​

  1. Đăng nhập vào entra.Microsoft.com với tư cách quản trị viên đối tượng thuê.
  2. Điều hướng đến Danh tính → Ứng dụng → Đăng ký ứng dụng.
  3. Nhấp vào Đăng ký mới.
  4. Điền vào:
    • Tên: Hermes Teams Meeting pipeline (hoặc bất kỳ tên nào bạn có thể nhận ra).
    • Các loại tài khoản được hỗ trợ: Chỉ các tài khoản trong thư mục tổ chức này (Người thuê duy nhất).
    • URI chuyển hướng: để trống — không cần xác thực chỉ ứng dụng.
  5. Nhấp vào Đăng ký.

Bạn sẽ đến trang tổng quan của ứng dụng. Sao chép hai giá trị:

  • ID ứng dụng (ứng dụng khách) → `MSGRAPH_CLIENT_ID

  • ID thư mục (đối tượng thuê) → `MSGRAPH_TENANT_ID

Bước 2: Tạo Bí mật khách hàng​

  1. Trong điều hướng bên trái, mở Chứng chỉ & bí mật.
  2. Nhấp vào Bí mật khách hàng mới.
  3. Mô tả: `Hermes-graph-secret

. Hết hạn: chọn một giá trị phù hợp với chính sách xoay vòng của bạn (thông thường là 6-24 tháng). 4. Nhấp vào Thêm. 5. Sao chép ngay cột Giá trị — cột này chỉ hiển thị một lần. Giá trị đó là `MSGRAPH_CLIENT_SECRET

.`> Cột Secret ID không phải là cột bí mật. Bạn muốn cột Giá trị.

Bước 3: Cấp quyền cho API đồ thị​

Quy trình sử dụng một bộ quyền ứng dụng khả thi tối thiểu. Chỉ thêm những gì bạn cần; mỗi cái mở rộng những gì ứng dụng có thể đọc cho toàn bộ đối tượng thuê.

  1. Trong điều hướng bên trái, hãy mở Quyền API.
  2. Nhấp vào Thêm quyền → Microsoft Graph → Quyền ứng dụng.
  3. Thêm các quyền từ bảng bên dưới phù hợp với những gì bạn muốn quy trình thực hiện.
  4. Sau khi thêm, hãy nhấp vào **Cấp sự đồng ý của quản trị viên cho

<your tenant>

**. Cột Trạng thái sẽ chuyển sang dấu kiểm màu xanh lục cho mọi quyền.

Bắt buộc đối với bản tóm tắt đầu tiên trong bảng điểm​

| Giấy phép | Ứng dụng này cho phép ứng dụng làm gì | |----------||--------------------------| | OnlineMeetings.Read.All | Đọc siêu dữ liệu cuộc họp trực tuyến của Teams (chủ đề, người tham gia, URL tham gia). | | OnlineMeetingTranscript.Read.All | Đọc bản ghi cuộc họp do Teams tạo. |

Cần thiết để ghi dự phòng (khi không có bản ghi)​

| Giấy phép | Ứng dụng này cho phép ứng dụng làm gì | |----------||--------------------------| | OnlineMeetingRecording.Read.All | Tải xuống bản ghi cuộc họp Teams để xử lý STT ngoại tuyến. | | CallRecords.Read.All | Giải quyết cuộc họp từ bản ghi cuộc gọi khi chỉ biết URL tham gia. |

Cần thiết để gửi bản tóm tắt gửi đi (Chỉ chế độ biểu đồ)​

Nếu platforms.teams.extra.delivery_mode là `graph

, quy trình sẽ đăng các bản tóm tắt vào kênh Nhóm hoặc trò chuyện qua API Đồ thị. Hãy bỏ qua những điều này nếu bạn sử dụng chế độ phân phối `incoming_webhook

.

| Giấy phép | Ứng dụng này cho phép ứng dụng làm gì | |----------||--------------------------| | ChannelMessage.Send | Đăng tin nhắn lên các kênh Teams thay mặt cho ứng dụng. | | Chat.ReadWrite.All | Đăng tin nhắn vào cuộc trò chuyện 1:1 và nhóm (chỉ khi bạn đặt chat_id làm mục tiêu gửi). |

Không khuyến khích​

OnlineMeetings.ReadWrite.All / Chat.ReadWrite không có

.All ` — rộng hơn nhu cầu của đường ống.

  • Quyền được ủy quyền — quy trình sử dụng luồng chỉ dành cho ứng dụng (thông tin xác thực của khách hàng); quyền được ủy quyền sẽ không hoạt động nếu người dùng không đăng nhập.

Bước 4: (Khuyến nghị) Phạm vi ứng dụng với Chính sách truy cập ứng dụng​

Theo mặc định, các quyền của ứng dụng như OnlineMeetings.Read.All cấp cho ứng dụng quyền truy cập vào mọi cuộc họp trong đối tượng thuê. Đối với các bản demo của đối tác và người thuê nhà phát triển thì điều đó là ổn; đối với sản xuất, bạn gần như chắc chắn muốn hạn chế những cuộc họp của người dùng mà ứng dụng có thể đọc.Microsoft cung cấp Chính sách truy cập ứng dụng cho Teams chính xác cho việc này. Chính sách này chỉ dành cho PowerShell; không có giao diện người dùng cổng thông tin cho nó.

Từ quản trị viên PowerShell có cài đặt và kết nối mô-đun MicrosoftTeams ( `Connect-MicrosoftTeams

):


# Create a policy scoped to the Hermes app
New-CsApplicationAccessPolicy 

  -Identity "Hermes-Meeting-pipeline-Policy" 

  -AppIds "&lt;MSGRAPH_CLIENT_ID>" 

  -Description "Restrict Hermes meeting pipeline to allow-listed users"

# Grant the policy to specific users whose meetings the pipeline may read
Grant-CsApplicationAccessPolicy 

  -PolicyName "Hermes-Meeting-pipeline-Policy" 

  -Identity "alice@example.com"

Grant-CsApplicationAccessPolicy 

  -PolicyName "Hermes-Meeting-pipeline-Policy" 

  -Identity "bob@example.com"

`
``Việc nhân giống có thể mất tới 30 phút sau khi cấp. Xác minh với:

``` powershell
Test-CsApplicationAccessPolicy -Identity "alice@example.com" -AppId "&lt;MSGRAPH_CLIENT_ID"

`
``Nếu không có chính sách này, **bất kỳ** cuộc họp nào của người dùng đều có thể đọc được — đó là quyền cấp phép về mặt kỹ thuật. Đừng bỏ qua bước này đối với người thuê sản xuất.

## Bước 5: Viết thông tin xác thực vào tệp Env của bạn

Đặt ba giá trị bạn đã thu thập vào 

~/.Hermes/.env

:

`bash
MSGRAPH_TENANT_ID=&lt;directory-tenant-id
MSGRAPH_CLIENT_ID=&lt;application-CLIent-id
MSGRAPH_CLIENT_SECRET=&lt;CLIent-secret-value

`
``Đặt quyền truy cập tệp để chỉ bạn mới có thể đọc được bí mật:

`bash
chmod 600 ~/.Hermes/.env

`

## Bước 6: Xác minh luồng Token

Hermes gửi bản thử nghiệm khói xác thực đồ thị. Từ bản cài đặt Hermes của bạn:

`Python
Python -c "
 import asyncio
from tools.Microsoft_graph_auth import MicrosoftGraphTokenProvider
provider = MicrosoftGraphTokenProvider.from_env()
token = asyncio.run(provider.get_access_token())
print('Token acquired, length:', len(token))
print(provider.inspect_token_health())
"

`
``Lần chạy thành công sẽ in ra một chuỗi mã thông báo dài và lệnh tình trạng hiển thị 
`cached: True
` và giá trị 
`expires_in_seconds
` gần 3600. Các lỗi tạo ra 
`MicrosoftGraphTokenError
` với mã lỗi Azure — phổ biến nhất là:

| Lỗi Azure | Ý nghĩa | Sửa chữa |
|-------------|----------|------|
| 
`AADSTS7000215: Invalid CLIent secret
` | Giá trị bí mật không khớp hoặc đã hết hạn. | Tạo bí mật mới ở bước 2; cập nhật 

.env

. |
| 
`AADSTS700016: Application not found
` | 
`MSGRAPH_CLIENT_ID
` sai hoặc người thuê sai. | Kiểm tra kỹ các giá trị ở bước 1 có phải từ cùng một ứng dụng hay không. |
| 
`AADSTS90002: Tenant not found
` | Lỗi đánh máy trong 
`MSGRAPH_TENANT_ID

. | Sao chép lại ID Thư mục (đối tượng thuê) từ phần tổng quan về ứng dụng. |
| 
`insufficient_claims
` tại thời điểm gọi (không phải thời gian mã thông báo) | Mã thông báo nhận được nhưng Biểu đồ trả về 401/403. | Bạn đã bỏ qua bước 3 sự đồng ý của quản trị viên hoặc đã thêm quyền nhưng chưa đồng ý lại. Xem lại các quyền của API và nhấp lại vào **Cấp sự đồng ý của quản trị viên**. |

## Xoay bí mật của khách hàng

Bí mật của khách hàng Azure có thời hạn sử dụng khó khăn. Trước khi của bạn hết hạn:
1. Tạo bí mật khách hàng thứ hai ở bước 2 mà không xóa bí mật đầu tiên.

2. Cập nhật 
`MSGRAPH_CLIENT_SECRET
` trong 

~/.Hermes/.env
` với giá trị mới.
3. Khởi động lại cổng để chọn bí mật mới: 
`Hermes gateway restart

.
4. Xác minh bằng thử nghiệm khói ở trên.
5. Xóa bí mật cũ khỏi cổng Azure.

## Các bước tiếp theo

Khi thông tin xác thực được xác minh rõ ràng, hãy tiếp tục với:
- **Thiết lập trình nghe Webhook** — thiết lập nền tảng cổng 
`msgraph_webhook
` để nhận thông báo thay đổi Biểu đồ.
- **Cấu hình đường dẫn** — định cấu hình thời gian chạy đường dẫn cuộc họp Teams và toán tử CLI.
- **Gửi đi** — gửi bản tóm tắt trở lại kênh Nhóm hoặc trò chuyện.

Các trang đó nằm dọc theo các PR có thêm thời gian chạy tương ứng. Việc thiết lập thông tin xác thực này là điều kiện tiên quyết độc lập và có thể hoàn thành trước một cách an toàn.