获取用户的邮箱设置Update user mailbox settings

命名空间:microsoft.graphNamespace: microsoft.graph

启用、配置或禁用以下一个或多个设置作为用户的mailboxSettings的一部分:Enable, configure, or disable one or more of the following settings as part of a user's mailboxSettings:

  • 自动答复(收到发件人的电子邮件时自动通知发件人)automatic replies (notify people automatically upon receipt of their email)
  • dateFormatdateFormat
  • delegateMeetingMessageDeliveryOptionsdelegateMeetingMessageDeliveryOptions
  • 区域设置(语言和国家/地区)locale (language and country/region)
  • timeFormattimeFormat
  • 时区time zone
  • 工作时间working hours

更新用户的首选日期或时间格式时,请分别指定短日期短时间格式。When updating the preferred date or time format for a user, specify it in respectively, the short date or short time format.

更新用户的首选时区时,在 Windows 或Internet 分配的号码颁发机构(IANA)的时区(也称为 "Olson 时区")格式中指定它。When updating the preferred time zone for a user, specify it in the Windows or Internet Assigned Numbers Authority (IANA) time zone (also known as Olson time zone) format. 您还可以进一步自定义时区,如下面的示例 2所示。You can also further customize the time zone as shown in example 2 below.

提示

您不能创建或删除任何邮箱设置。You cannot create or delete any mailbox settings.

权限Permissions

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) MailboxSettings.ReadWriteMailboxSettings.ReadWrite
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) MailboxSettings.ReadWriteMailboxSettings.ReadWrite
应用程序Application MailboxSettings.ReadWriteMailboxSettings.ReadWrite

HTTP 请求HTTP request

PATCH /me/mailboxSettings
PATCH /users/{id|userPrincipalName}/mailboxSettings

可选的查询参数Optional query parameters

此方法支持 OData 查询参数 来帮助自定义响应。This method supports the OData Query Parameters to help customize the response.

请求标头Request headers

名称Name 类型Type 说明Description
AuthorizationAuthorization stringstring Bearer {token}。必需。Bearer {token}. Required.

请求正文Request body

在请求正文中,提供应更新的相关属性的值。请求正文中不包括的现有属性将保留其以前的值,或根据对其他属性值的更改重新计算。为了获得最佳性能,不应包括尚未更改的现有值。以下是可写/可更新的属性:In the request body, supply the values for the relevant properties that should be updated. Existing properties that are not included in the request body will maintain their previous values or be recalculated based on changes to other property values. For best performance you shouldn't include existing values that haven't changed. The following are the writable/updatable properties:

属性Property 类型Type 说明Description
automaticRepliesSettingautomaticRepliesSetting automaticRepliesSettingautomaticRepliesSetting 自动通知发件人有传入电子邮件(包含一封来自已登录用户的邮件)的配置设置。Configuration settings to automatically notify the sender of an incoming email with a message from the signed-in user. 只能将此类通知设置为将来日期范围。You can set such notifications for only a future date range.
dateFormatdateFormat stringstring 用户邮箱的日期格式。The date format for the user's mailbox.
delegateMeetingMessageDeliveryOptionsdelegateMeetingMessageDeliveryOptions delegateMeetingMessageDeliveryOptionsdelegateMeetingMessageDeliveryOptions 如果用户具有日历代理,则指定代理、邮箱所有者,还是同时接收会议邮件和会议响应。If the user has a calendar delegate, this specifies whether the delegate, mailbox owner, or both receive meeting messages and meeting responses. 可取值为:sendToDelegateAndInformationToPrincipalsendToDelegateAndPrincipalsendToDelegateOnlyPossible values are: sendToDelegateAndInformationToPrincipal, sendToDelegateAndPrincipal, sendToDelegateOnly.
语言language localeInfolocaleInfo 用户的区域设置信息,包括首选语言和国家/地区。The locale information for the user, including the preferred language and country/region.
timeFormattimeFormat stringstring 用户邮箱的时间格式。The time format for the user's mailbox.
timeZonetimeZone stringstring 用户邮箱的默认时区。The default time zone for the user's mailbox.
workingHoursworkingHours workingHoursworkingHours 用户工作的小时数、一周的天数和时区。The hours, days of a week, and time zone that the user works.

响应Response

如果成功,此方法在响应200 OK正文中返回响应代码和mailboxSettings对象的更新的属性。If successful, this method returns a 200 OK response code and the updated properties of a mailboxSettings object in the response body.

错误Errors

将工作时间设置为不适当的值可能会返回以下错误。Setting working hours with inappropriate values may return the following errors.

应用场景Scenario HTTP 状态代码HTTP status code 错误代码Error code 错误消息Error message
startTimeendTime 无效Invalid startTime or endTime 400400 RequestBodyReadRequestBodyRead 无法将文本“08”转换为预期类型“Edm.TimeOfDay”。Cannot convert the literal '08' to the expected type 'Edm.TimeOfDay'.
开始时间大于结束时间Start time is greater than end time 400400 ErrorInvalidTimeSettingsErrorInvalidTimeSettings 开始时间应早于结束时间。Start Time should occur before End Time.
daysOfWeek 中的天数无效Invalid day in daysOfWeek 400400 InvalidArgumentsInvalidArguments 未找到请求值“RandomDay”。Requested value 'RandomDay' was not found.
timeZone 无效Invalid timeZone 400400 InvalidTimeZoneInvalidTimeZone 提供的时区设置无效。Time Zone settings provided are invalid.

示例Examples

示例 1Example 1

请求Request

第一个示例通过设置 automaticRepliesSetting 属性的以下属性来启用对日期范围的自动答复:statusscheduledStartDateTimescheduledEndDateTimeThe first example enables automatic replies for a date range, by setting the following properties of the automaticRepliesSetting property: status, scheduledStartDateTime and scheduledEndDateTime.

PATCH https://graph.microsoft.com/v1.0/me/mailboxSettings
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/mailboxSettings",
    "automaticRepliesSetting": {
        "status": "Scheduled",
        "scheduledStartDateTime": {
          "dateTime": "2016-03-20T18:00:00.0000000",
          "timeZone": "UTC"
        },
        "scheduledEndDateTime": {
          "dateTime": "2016-03-28T18:00:00.0000000",
          "timeZone": "UTC"
        }
    }
}

响应Response

该响应包括自动答复的更新设置。The response includes the updated settings for automatic replies. 注意:为简洁起见,可能会截断此处显示的响应对象。Note: The response object shown here may be truncated for brevity. 将从实际调用中返回所有属性。All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/mailboxSettings",
    "automaticRepliesSetting": {
        "status": "scheduled",
        "externalAudience": "all",
        "scheduledStartDateTime": {
            "dateTime": "2016-03-20T02:00:00.0000000",
            "timeZone": "UTC"
        },
        "scheduledEndDateTime": {
            "dateTime": "2016-03-28T02:00:00.0000000",
            "timeZone": "UTC"
        },
    "internalReplyMessage": "<html>\n<body>\n<p>I'm at our company's worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n",
    "externalReplyMessage": "<html>\n<body>\n<p>I'm at the Contoso worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n"
    }
}

示例 2Example 2

请求Request

第二个示例通过将 timeZone 属性设置为自定义时区,为登录用户的工作时间自定义时区。The second example customizes the time zone for the working hours of the signed-in user, by setting the timeZone property to a custom time zone.

PATCH https://graph.microsoft.com/v1.0/me/mailboxSettings
Content-Type: application/json

{
  "workingHours": {
      "endTime" : "18:30:00.0000000", 
      "daysOfWeek": [ 
          "Monday", 
          "Tuesday", 
          "Wednesday", 
          "Thursday", 
          "Friday", 
          "Saturday" 
      ], 
      "timeZone" : { 
         "@odata.type": "#microsoft.graph.customTimeZone", 
         "bias":-300, 
         "name": "Customized Time Zone",
         "standardOffset":{   
           "time":"02:00:00.0000000", 
           "dayOccurrence":2, 
           "dayOfWeek":"Sunday", 
           "month":10, 
           "year":0 
         }, 
         "daylightOffset":{   
           "daylightBias":100, 
           "time":"02:00:00.0000000", 
           "dayOccurrence":4, 
           "dayOfWeek":"Sunday", 
           "month":5, 
           "year":0 
         } 
      } 
  }
} 

响应Response

下面是一个响应示例。注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。Here is an example of the response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('94447c6e-ea4c-494c-a9ed-d905e366c5cb')/mailboxSettings",
    "workingHours":{
        "daysOfWeek":[
            "monday",
            "tuesday",
            "wednesday",
            "thursday",
            "friday",
            "saturday"
        ],
        "startTime":"09:00:00.0000000",
        "endTime":"18:30:00.0000000",
        "timeZone":{
            "@odata.type":"#microsoft.graph.customTimeZone",
            "bias":-200,
            "name":"Customized Time Zone",
            "standardOffset":{
                "time":"02:00:00.0000000",
                "dayOccurrence":4,
                "dayOfWeek":"sunday",
                "month":5,
                "year":0
            },
            "daylightOffset":{
                "daylightBias":-100,
                "time":"02:00:00.0000000",
                "dayOccurrence":2,
                "dayOfWeek":"sunday",
                "month":10,
                "year":0
            }
        }
    }
}