sharepoint search/query 返回 SearchRequest Invalid (Region is required when request with application p
这个错误 **`SearchRequest Invalid (Region is required when request with application permission.)`** 是一个非常具体的 Microsoft Graph API 限制。
### 错误原因
当你使用 **应用程序权限 (Application Permissions)**（即 Client Credentials Flow，没有用户上下文）调用 `search/query` 接口时，Microsoft 出于 **数据 residency（数据驻留）** 和 **多地理位置 (Multi-Geo)** 合规性的考虑，强制要求你在请求体中明确指定搜索的 **地理区域 (Region)**。
因为没有了“登录用户”的上下文（通常用户的配置文件中包含首选数据位置），API 无法自动判断应该去哪个地理区域的数据中心搜索数据。
### 解决方案
你需要在请求体的 `requests` 数组对象中，添加 **`region`** 属性。
#### 1. 修改请求 JSON
在 `requests` 数组的每个对象中，加入 `"region": "<区域代码>"`。
**修改前的示例 (报错):**
```json
{
"requests": [
{
"entityTypes": ["driveItem"],
"query": {
"queryString": "合同"
}
}
]
}
```
**修改后的示例 (修复):**
```json
POST https://graph.microsoft.com/v1.0/search/query
Content-Type: application/json
{
"requests": [
{
"entityTypes": ["driveItem"],
"query": {
"queryString": "合同"
},
"region": "USA" // <--- 添加这一行，指定区域代码
}
]
}
```
#### 2. 如何确定正确的区域代码 (Region Code)
区域代码取决于你的 Microsoft 365 租户配置。常见的代码包括：
| 区域 | 代码 (Region Code) |
| :--- | :--- |
| **美国** | `USA` |
| **欧洲** | `EUR` |
| **亚太** | `APC` |
| **加拿大** | `CAN` |
| **英国** | `GBR` |
| **德国** | `DEU` |
| **法国** | `FRA` |
| **中国 (世纪互联)** | `CHN` (如果使用的是 `graph.microsoft.cn`) |
| **印度** | `IND` |
| **日本** | `JPN` |
| **韩国** | `KOR` |
| **澳大利亚** | `AUS` |
**如何查找你的租户区域代码：**
1. **SharePoint 管理员中心**：登录 -> **设置 (Settings)** -> **多地理位置 (Multi-geo)**。这里会列出你租户配置的所有地理位置及其代码。
2. **默认情况**：如果你的租户是单地理位置（没有开启 Multi-Geo），通常尝试使用 **`USA`** 作为默认值。如果是中国租户 (`graph.microsoft.cn`)，尝试 **`CHN`**。
3. **通过 API 探测**：如果不确定，可以尝试调用 `GET https://graph.microsoft.com/v1.0/organization` 查看租户信息，有时会有线索，但最直接的是试错或查看 admin 中心。
#### 3. 特殊情况：中国云 (世纪互联)
如果你使用的是 **中国云** (`https://graph.microsoft.cn`)：
* 确保你的 Base URL 是 `graph.microsoft.cn` 而不是 `graph.microsoft.com`。
* `region` 值通常应设置为 **`CHN`**。
* 如果是中国云单租户，有时可能不需要该参数，但既然报错说 required，请加上 `"region": "CHN"`。
### 替代方案：使用委派权限 (Delegated Permissions)
如果可能，建议改用 **委派权限**（即用户登录模式，Authorization Code Flow）。
* **原因**：在委派权限模式下，API 会根据**登录用户**的首选数据位置自动确定区域，通常**不需要**手动指定 `region` 参数。
* **权限**：需要 `Sites.Read.All` 或 `Sites.Search.All`。
### 总结检查清单
1. [ ] 确认使用的是 **应用程序权限 (Client Credentials)**。
2. [ ] 在 JSON 请求体的 `requests` 对象内添加 `"region": "代码"`。
3. [ ] 确认 Base URL 是否正确（全球云用 `.com`，中国云用 `.cn`）。
4. [ ] 确认区域代码与租户实际配置匹配（单 geo 租户通常试 `USA` 或 `CHN`）。
添加该参数后，重新发送请求即可解决此错误。