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

Trình nghe Webhook của Microsoft Graph

Nền tảng cổng msgraph_webhook là một trình xử lý sự kiện gửi đến. Đó là cách Hermes nhận được thông báo thay đổi từ Microsoft Graph — "một cuộc họp Teams đã kết thúc", "một tin nhắn mới đã đến trong cuộc trò chuyện này", "sự kiện lịch này đã được cập nhật". Khác với nền tảng teams (là nền tảng mà người dùng sử dụng bot trò chuyện) - nền tảng này là M365 nói với Hermes điều gì đó đã xảy ra, không phải một người.

Hiện tại, đối tượng sử dụng chính là quy trình tóm tắt cuộc họp trên Teams: Graph thông báo khi cuộc họp tạo ra bản ghi, quy trình tìm nạp bản ghi đó và Hermes đăng bản tóm tắt trở lại Teams. Các tài nguyên Đồ thị khác (

/chats/.../messages

,

/users/.../events

) sử dụng cùng một trình nghe — người tiêu dùng quy trình tiếp cận PR của riêng họ.

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

  • Thông tin xác thực ứng dụng Microsoft Graph — Register a Microsoft Graph Application
  • URL HTTPS công khai mà Microsoft Graph có thể tiếp cận (Graph không gọi điểm cuối riêng tư). Đường hầm dành cho nhà phát triển hoạt động để thử nghiệm; production cần một miền thực có chứng chỉ hợp lệ.
  • Một bí mật được chia sẻ mạnh mẽ để sử dụng làm giá trị `CLIentState

. Tạo bằng openSSL rand -hex 32 và đặt nó vào

~/.Hermes/.env dưới dạng MSGRAPH_WEBHOOK_CLIENT_STATE

.

Bắt đầu nhanh​

~/.Hermes/config.yaml ` tối thiểu:

platforms:
  msgraph_webhook:
    enabled: true
    extra:
      port: 8646
      CLIent_state: "replace-with-a-strong-secret"
      accepted_resources:

        - "communications/onlineMeetings"

`
``Hoặc thông qua các vars env trong 

~/.Hermes/.env
` (tự động hợp nhất khi khởi động):

``` bash
MSGRAPH_WEBHOOK_ENABLED=true
MSGRAPH_WEBHOOK_PORT=8646
MSGRAPH_WEBHOOK_CLIENT_STATE=<generate-with-openSSL-rand-hex-32>
MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings

`
``Khởi động cổng: 
`Hermes gateway run

. Người nghe bộc bạch:
- 
`POST /msgraph/webhook

 - thông báo thay đổi từ Biểu đồ

- 
`GET /msgraph/webhook?validationToken=...

 - Bắt tay xác thực đăng ký đồ thị
- 
`GET /health

 - đầu dò sẵn sàng với các bộ đếm được chấp nhận/trùng lặp

Hiển thị công khai người nghe (proxy ngược, đường hầm nhà phát triển, xâm nhập). URL thông báo của bạn cho các đăng ký Đồ thị là nguồn gốc HTTPS công khai của bạn, theo sau là 

/msgraph/webhook

:

`
https://ops.example.com/msgraph/webhook

`

## Cấu hình

Tất cả các cài đặt đều nằm trong 
`platforms.msgraph_webhook.extra

:

| Cài đặt | Mặc định | Mô tả |
|----------|----------|-------------|
| 
`host
` | 
`0.0.0.0
` | Địa chỉ liên kết cho người nghe HTTP. |
| 
`port
` | 
`8646
` | Cổng ràng buộc. |
| 
`webhook_path
` | 

/msgraph/webhook
` | Đường dẫn URL Biểu đồ POST tới. |
| 
`health_path
` | 

/health
` | Điểm cuối sẵn sàng. |
| 
`CLIent_state
` | — | Đồ thị bí mật được chia sẻ vang vọng trong mọi thông báo. So với 
`hmac.compare_digest

 - tạo bằng 
`openSSL rand -hex 32

. |
| 
`accepted_resources
` | 

[]
` (chấp nhận tất cả) | Danh sách cho phép các đường dẫn/mẫu tài nguyên đồ thị. Trailing 

*
` hoạt động như đối sánh tiền tố. 

/
` dẫn đầu được chấp nhận. Ví dụ: 

["communications/onlineMeetings", "chats/*/messages"]

. |
| 
`max_seen_receipts
` | 
`5000
` | Loại bỏ kích thước bộ đệm trùng lặp cho ID thông báo. Các mục cũ nhất bị loại bỏ khi đạt đến giới hạn. |
| 
`allowed_source_cidrs
` | 

[]
` (cho phép tất cả) | Danh sách cho phép IP nguồn tùy chọn. Xem bên dưới. |

Mỗi cài đặt cũng có một biến env tương đương (
`MSGRAPH_WEBHOOK_*

) hợp nhất vào cấu hình khi khởi động cổng - xem [environment variables reference](/docs/reference/environment-variables#Microsoft-graph-teams-meetings).

## Tăng cường bảo mật

### CLIentState là bước kiểm tra xác thực chính

Mọi thông báo Biểu đồ đều bao gồm chuỗi 
`CLIentState
` mà đăng ký của bạn đã đăng ký. Trình nghe từ chối bất kỳ thông báo nào có 
`CLIentState
` không khớp, sử dụng so sánh an toàn về thời gian. Đây là cơ chế được ghi lại của Microsoft — coi giá trị là bí mật được chia sẻ mạnh mẽ.

Nếu 
`CLIent_state
` không được đặt, trình nghe sẽ chấp nhận mọi POST được định dạng đúng. **Không chạy mà không có nó trong quá trình sản xuất.**

### Danh sách cho phép nguồn-IP (triển khai sản xuất)

Để sản xuất, hãy hạn chế trình nghe trong phạm vi IP nguồn webhook Graph đã xuất bản của Microsoft. Microsoft ghi lại phạm vi đầu ra theo [Office 365 IP Address and URL Web service](https://learn.Microsoft.com/en-us/Microsoft-365/enterprise/urls-and-ip-address-ranges). Cấu hình chúng như:

``` yaml
platforms:
  msgraph_webhook:
    enabled: true
    extra:
      CLIent_state: "..."
      allowed_source_cidrs:

        - "52.96.0.0/14"
        - "52.104.0.0/14"
        # ...add the current Microsoft 365 "Common" + "Teams" category egress ranges

`
``Hoặc dưới dạng một env var:

``` bash
MSGRAPH_WEBHOOK_ALLOWED_SOURCE_CIDRS="52.96.0.0/14,52.104.0.0/14"

`
``Danh sách cho phép trống = chấp nhận từ mọi nơi (mặc định; duy trì quy trình làm việc của đường hầm nhà phát triển). Chuỗi CIDR không hợp lệ ghi lại cảnh báo và bị bỏ qua. **Xem lại danh sách IP của Microsoft hàng quý** — danh sách này thay đổi.

### Chấm dứt HTTPS

Người nghe nói HTTP đơn giản. Chấm dứt TLS tại proxy ngược của bạn (Caddy, Nginx, Cloudflare Tunnel, AWS ALB) và proxy cho người nghe qua mạng cục bộ. Graph từ chối phân phối đến các điểm cuối không phải HTTPS, do đó, không có đường dẫn nào cho lưu lượng truy cập không được mã hóa tiếp cận bạn từ chính Graph.

### Vệ sinh ứng phó

Khi thành công, trình nghe trả về 
`202 Accepted
` với phần thân trống - các bộ đếm bên trong nằm ngoài phản hồi của dây. Người vận hành có thể quan sát số lượng thông qua 

/health

.Bảng mã trạng thái:

| Kết quả | Trạng thái |
|----------|--------|
| (Các) thông báo được chấp nhận hoặc bị loại trừ | 202 |
| Bắt tay xác thực (GET với 
`validationToken

) | 200 (lặp lại mã thông báo) |
| Mọi mục trong lô đều bị lỗi CLIentState | 403 |
| JSON không đúng định dạng/thiếu mảng 
`value

/tài nguyên không xác định | 400 |
| IP nguồn không có trong danh sách cho phép | 403 |
| NHẬN trần mà không có 
`validationToken
` | 400 |

## Khắc phục sự cố

| Vấn đề | Kiểm tra những gì |
|----------|---------------|
| Xác thực đăng ký đồ thị không thành công | URL công khai có thể truy cập được, đường dẫn 

/msgraph/webhook
` khớp với, GET với 
`validationToken
` lặp lại nguyên văn mã thông báo là 
`text/plain
` trong vòng 10 giây. |
| Thông báo POST nhưng không có gì nhập |

CLIent_state
` khớp với những gì bạn đã đăng ký đăng ký. Chạy lại 
`openSSL rand -hex 32
` và tạo đăng ký mới nếu giá trị bị thay đổi. Kiểm tra 
`accepted_resources
` có bao gồm đường dẫn tài nguyên mà Biểu đồ đang gửi hay không. |
| Mọi thông báo 403s |

CLIentState
` không khớp (giả mạo hoặc đăng ký được đăng ký với giá trị khác). Tạo lại đăng ký với 
`Hermes teams-pipeline subscribe --CLIent-state "$MSGRAPH_WEBHOOK_CLIENT_STATE" ...
` (đi kèm với PR thời gian chạy đường ống). |
| Trình nghe khởi động nhưng 
`curl http://localhost:8646/health
` bị treo | Va chạm ràng buộc cổng. Kiểm tra 
`ss -tlnp \| grep 8646
` và thay đổi 
`port:
` nếu cần. |
| Yêu cầu đồ thị thực từ Microsoft nhận được 403'd | Danh sách cho phép IP nguồn quá hẹp. Xóa tạm thời 
`allowed_source_cidrs

, xác nhận luồng lưu lượng truy cập, sau đó mở rộng danh sách để bao gồm phạm vi đầu ra hiện tại của Microsoft. |

## Tài liệu liên quan
- [Register a Microsoft Graph Application](/docs/guides/Microsoft-graph-app-registration) - Điều kiện tiên quyết để đăng ký ứng dụng Azure

- [Environment Variables → Microsoft Graph](/docs/reference/environment-variables#Microsoft-graph-teams-meetings) - danh sách var env đầy đủ
- [Microsoft Teams bot setup](/docs/user-guide/messaging/teams) — nền tảng khác cho phép người dùng trò chuyện với Hermes trong Teams