如何通过GraphApi或PowerShell批量修改Viva Insights办公/午休时间

Viva Insights的办公/午休时间存储在Microsoft Graph的userWorkTimeSettings资源中，不属于Exchange cmdlet的管理范围，因此你之前尝试的Get-Mailbox等命令无法获取到相关配置。以下是通过Graph API和PowerShell批量修改的具体方法：

一、Microsoft Graph API 方式 #

1. 准备权限与身份验证 #

批量操作需要使用应用权限（委托权限仅能修改当前登录用户的设置），需在Azure AD中注册应用并授予以下权限之一：

• User.ReadWrite.All（推荐，仅需用户读写权限）
• Directory.ReadWrite.All（权限范围更大，按需选择）

获取应用的访问令牌后，即可调用Graph API进行批量修改。

2. 单用户修改请求 #

使用PATCH请求修改单个用户的配置，请求示例：

PATCH https://graph.microsoft.com/v1.0/users/{user-upn-or-id}/settings/workTimeSettings
Content-Type: application/json

{
  "daysOfWeek": ["monday", "tuesday", "wednesday", "thursday", "friday"],
  "startTime": "09:00:00",
  "endTime": "18:00:00",
  "timeZone": "China Standard Time",
  "breakSchedule": {
    "recurrence": {
      "pattern": {
        "type": "daily",
        "daysOfWeek": ["monday", "tuesday", "wednesday", "thursday", "friday"]
      },
      "range": {
        "type": "noEnd"
      }
    },
    "startTime": "12:00:00",
    "endTime": "13:00:00"
  }
}

3. 批量操作优化 #

针对2000+用户，使用Graph的批量请求API（一次最多包含20个独立请求）减少网络开销，示例批量请求体：

POST https://graph.microsoft.com/v1.0/$batch
Content-Type: application/json

{
  "requests": [
    {
      "id": "1",
      "method": "PATCH",
      "url": "/users/user1@contoso.com/settings/workTimeSettings",
      "body": {
        "daysOfWeek": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "startTime": "09:00:00",
        "endTime": "18:00:00",
        "timeZone": "China Standard Time",
        "breakSchedule": {
          "recurrence": {
            "pattern": {
              "type": "daily",
              "daysOfWeek": ["monday", "tuesday", "wednesday", "thursday", "friday"]
            },
            "range": {
              "type": "noEnd"
            }
          },
          "startTime": "12:00:00",
          "endTime": "13:00:00"
        }
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "2",
      "method": "PATCH",
      "url": "/users/user2@contoso.com/settings/workTimeSettings",
      "body": {...}, // 同上述配置
      "headers": {
        "Content-Type": "application/json"
      }
    }
  ]
}

二、PowerShell 方式（使用Microsoft Graph PowerShell模块） #

1. 安装并配置模块 #

# 安装Microsoft Graph Users模块
Install-Module Microsoft.Graph.Users -Force -AllowClobber

# 使用应用权限连接Graph（推荐使用证书认证，更安全）
Connect-MgGraph -ClientId "你的应用ID" -TenantId "你的租户ID" -CertificateThumbprint "证书指纹"
# 若使用客户端密钥（仅测试环境推荐）
# Connect-MgGraph -ClientId "你的应用ID" -TenantId "你的租户ID" -ClientSecret (ConvertTo-SecureString "你的客户端密钥" -AsPlainText -Force)

2. 批量修改脚本示例 #

假设你有一个包含用户UPN的CSV文件users.csv（列名：UserPrincipalName），脚本如下：

# 读取用户列表
$users = Import-Csv -Path "C:\temp\users.csv"

# 定义统一的办公/午休配置
$workTimeSettings = @{
    DaysOfWeek = @("monday", "tuesday", "wednesday", "thursday", "friday")
    StartTime = "09:00:00"
    EndTime = "18:00:00"
    TimeZone = "China Standard Time"
    BreakSchedule = @{
        Recurrence = @{
            Pattern = @{
                Type = "daily"
                DaysOfWeek = @("monday", "tuesday", "wednesday", "thursday", "friday")
            }
            Range = @{
                Type = "noEnd"
            }
        }
        StartTime = "12:00:00"
        EndTime = "13:00:00"
    }
}

# 循环修改每个用户
foreach ($user in $users) {
    try {
        Update-MgUserSettingWorkTimeSetting -UserId $user.UserPrincipalName -BodyParameter $workTimeSettings
        Write-Host "已成功修改用户 $($user.UserPrincipalName) 的配置"
        # 添加节流延迟，避免触发Graph速率限制
        Start-Sleep -Milliseconds 500
    }
    catch {
        Write-Host "修改用户 $($user.UserPrincipalName) 失败：$_" -ForegroundColor Red
    }
}

注意事项 #

• 时区需使用Windows时区ID（如China Standard Time），而非IANA时区格式。
• 批量操作时务必添加节流控制，避免触发Graph API的速率限制（默认限制为每租户每分钟1000次请求）。
• 若需针对不同用户设置不同配置，可在CSV中增加对应列，动态生成$workTimeSettings参数。

内容的提问来源于stack exchange，提问作者hdsouza