Office 365 IP 地址和 URL Web 服务Office 365 IP Address and URL web service

Office 365 IP 地址和 URL Web 服务可帮助你更好地识别和区分 Office 365 网络流量,以便更轻松地评估、配置和及时了解最新变更。The Office 365 IP Address and URL web service helps you better identify and differentiate Office 365 network traffic, making it easier for you to evaluate, configure, and stay up to date with changes. 此基于 REST 的 Web 服务将取代自 2018 年 10 月 2 日开始逐步停止使用的旧版 XML 可下载文件。This REST-based web service replaces the previous XML downloadable files, which were phased out on October 2, 2018.

作为客户或网络外围设备供应商,你可以针对 Office 365 IP 地址和 FQDN 条目构建 Web 服务。As a customer or a network perimeter device vendor, you can build against the web service for Office 365 IP address and FQDN entries. 你可以使用以下 URL 直接访问 Web 浏览器中的数据:You can access the data directly in a web browser using these URLs:

作为客户,你可以使用这项 Web 服务:As a customer, you can use this web service to:

  • 将 PowerShell 脚本更新为获取 Office 365 终结点数据,并修改网络设备的任何格式。Update your PowerShell scripts to obtain Office 365 endpoint data and modify any formatting for your networking devices.
  • 根据此类信息更新已部署到客户端计算机的 PAC 文件。Use this information to update PAC files deployed to client computers.

作为网络外围设备供应商,你可以使用这项 Web 服务:As a network perimeter device vendor, you can use this web service to:

  • 创建并测试设备软件,以下载自动配置列表。Create and test device software to download the list for automated configuration.
  • 检查当前版本。Check for the current version.
  • 获取最新变更。Get the current changes.

备注

如果正在使用 Azure ExpressRoute 连接到 Office 365,请查看适用于 Office 365 的 Azure ExpressRoute 以熟悉 Azure expressroute 支持的 Office 365 服务。If you are using Azure ExpressRoute to connect to Office 365, please review Azure ExpressRoute for Office 365 to familiarize yourself with the Office 365 services supported over Azure ExpressRoute. 另请查看 Office 365 URL 和 IP 地址范围,以了解 Office 365 应用程序的哪些网络请求需要 Internet 连接。Also review the article Office 365 URLs and IP address ranges to understand which network requests for Office 365 applications require Internet connectivity. 这有助于更好地配置外围安全设备。This will help to better configure your perimeter security devices.

有关详细信息,请参阅:For more information, see:

通用参数Common parameters

下面两个参数是所有 Web 服务方法的通用参数:These parameters are common across all the web service methods:

  • format=<JSON | CSV> — 默认情况下,返回数据的格式为 JSON。format=<JSON | CSV> — By default, the returned data format is JSON. 使用此可选参数返回采用逗号分隔值 (CSV) 格式的数据。Use this optional parameter to return the data in comma-separated values (CSV) format.

  • ClientRequestId=<guid> — 为客户端关联生成的所需 GUID。ClientRequestId=<guid> — A required GUID that you generate for client association. 为调用 Web 服务的每台计算机生成唯一的 GUID(此页面上包含的脚本将为你生成 GUID)。Generate a unique GUID for each machine that calls the web service (the scripts included on this page generate a GUID for you). 请勿使用以下示例中所示的 GUID,因为它们将来可能会被 Web 服务阻止。Do not use the GUIDs shown in the following examples because they might be blocked by the web service in the future. GUID 格式为 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,其中 x 表示一个十六进制数字。GUID format is xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x represents a hexadecimal number.

    若要生成 GUID,你可以使用 New-Guid PowerShell 命令,或使用在线 GUID 生成器等在线服务。To generate a GUID, you can use the New-Guid PowerShell command, or use an online service such as Online GUID Generator.

版本 Web 方法Version web method

Microsoft 会在每个月末更新 Office 365 IP 地址和 FQDN 条目。Microsoft updates the Office 365 IP address and FQDN entries at the end of each month. 出于支持事件、安全更新或其他操作要求,有时会发布带外更新。Out-of-band updates are sometimes published due to support incidents, security updates or other operational requirements.

我们为每个已发布实例的数据分配了版本号,你可以通过版本 Web 方法检查每个 Office 365 服务实例的最新版本。The data for each published instance is assigned a version number, and the version web method enables you to check for the latest version of each Office 365 service instance. 我们建议每小时检查版本的次数不要超过一次。We recommend that you check the version not more than once an hour.

版本 Web 服务的参数如下:Parameters for the version web method are:

  • AllVersions=<true | false> — 默认情况下,返回的版本为最新的。AllVersions=<true | false> — By default, the version returned is the latest. 包括此可选参数,以请求首次发布 Web 服务之后的所有已发布版本。Include this optional parameter to request all published versions since the web service was first released.
  • Format=<JSON | CSV | RSS> — 除了 JSON 和 CSV 格式,版本 Web 服务还支持 RSS。Format=<JSON | CSV | RSS> — In addition to the JSON and CSV formats, the version web method also supports RSS. 可以结合使用此可选参数及 AllVersions=true 参数,以请求可用于 Outlook 或其他 RSS 读取器的 RSS 源。You can use this optional parameter along with the AllVersions=true parameter to request an RSS feed that can be used with Outlook or other RSS readers.
  • Instance=<Worldwide | China | Germany | USGovDoD | USGovGCCHigh> — 此可选参数用于指定返回其版本的实例。Instance=<Worldwide | China | Germany | USGovDoD | USGovGCCHigh> — This optional parameter specifies the instance to return the version for. 如果圣罗,则会返回所有实例。If omitted, all instances are returned. 有效实例包括:Worldwide、China、Germany、USGovDoD、USGovGCCHigh。Valid instances are: Worldwide, China, Germany, USGovDoD, USGovGCCHigh.

版本 Web 方法不受速率限制,并且决不会返回 429 HTTP 响应代码。The version web method is not rate limited and does not ever return 429 HTTP Response Codes. 对版本 Web 方法的响应包括一个缓存控制标头,它建议将数据缓存 1 小时。The response to the version web method does include a cache-control header recommending caching of the data for 1 hour. 版本 Web 方法的结果可以是一条记录,也可以是一组记录。The result from the version web method can be a single record or an array of records. 每条记录均包含以下元素:The elements of each record are:

  • instance — Office 365 服务实例的短名称。instance — The short name of the Office 365 service instance.
  • latest — 指定实例的终结点的最新版本。latest — The latest version for endpoints of the specified instance.
  • 版本 — 指定实例的所有旧版本的列表。versions — A list of all previous versions for the specified instance. 仅当 AllVersions 参数为 true 时才包含此元素。This element is only included if the AllVersions parameter is true.

示例:Examples:

示例 1 请求 URI:https://endpoints.office.com/version?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7Example 1 request URI: https://endpoints.office.com/version?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7

此 URI 返回每个 Office 365 服务实例的最新版本。示例结果如下:This URI returns the latest version of each Office 365 service instance. Example result:

[
 {
  "instance": "Worldwide",
  "latest": "2018063000"
 },
 {
  "instance": "USGovDoD",
  "latest": "2018063000"
 },
 {
  "instance": "USGovGCCHigh",
  "latest": "2018063000"
 },
 {
  "instance": "China",
  "latest": "2018063000"
 },
 {
  "instance": "Germany",
  "latest": "2018063000"
 }
]

重要

这些 URI 中 ClientRequestID 参数的 GUID 只是个例子。若要试用 Web 服务 URI,请生成你自己的 GUID。这项 Web 服务将来可能会屏蔽这些示例中的 GUID。The GUID for the ClientRequestID parameter in these URIs are only an example. To try the web service URIs out, generate your own GUID. The GUIDs shown in these examples may be blocked by the web service in the future.

示例 2 请求 URI:https://endpoints.office.com/version/Worldwide?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7Example 2 request URI: https://endpoints.office.com/version/Worldwide?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7

此 URI 返回指定 Office 365 服务实例的最新版本。示例结果如下:This URI returns the latest version of the specified Office 365 service instance. Example result:

{
 "instance": "Worldwide",
 "latest": "2018063000"
}

示例 3 请求 URI:https://endpoints.office.com/version/Worldwide?Format=CSV&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7Example 3 request URI: https://endpoints.office.com/version/Worldwide?Format=CSV&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7

此 URI 显示 CSV 格式输出。示例结果如下:This URI shows output in CSV format. Example result:

instance,latest
Worldwide,2018063000

示例 4 请求 URI:https://endpoints.office.com/version/Worldwide?AllVersions=true&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7Example 4 request URI: https://endpoints.office.com/version/Worldwide?AllVersions=true&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7

此 URI 显示 Office 365 全球服务实例的所有已发布旧版本。示例结果如下:This URI shows all prior versions that have been published for the Office 365 worldwide service instance. Example result:

{
  "instance": "Worldwide",
  "latest": "2018063000",
  "versions": [
    "2018063000",
    "2018062000"
  ]
}

示例 5 RSS 源 URI:https://endpoints.office.com/version/worldwide?clientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7&allVersions=true&format=RSSExample 5 RSS Feed URI: https://endpoints.office.com/version/worldwide?clientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7&allVersions=true&format=RSS

此 URI 显示已发布版本的 RSS 源,其中包含指向每个版本的变更列表的链接。示例结果如下:This URI shows an RSS feed of the published versions that include links to the list of changes for each version. Example result:

<?xml version="1.0" encoding="ISO-8859-1"?>
<rss version="2.0" xmlns:a10="https://www.w3.org/2005/Atom">
<channel>
<link>https://aka.ms/o365ip</link>
<description/>
<language>en-us</language>
<lastBuildDate>Thu, 02 Aug 2018 00:00:00 Z</lastBuildDate>
<item>
<guid isPermaLink="false">2018080200</guid>
<link>https://endpoints.office.com/changes/Worldwide/2018080200?singleVersion&clientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7</link> <description>Version 2018080200 includes 2 changes. IPs: 2 added and 0 removed.</description>
<pubDate>Thu, 02 Aug 2018 00:00:00 Z</pubDate>
</item>

终结点 Web 方法Endpoints web method

终结点 Web 方法可返回组成 Office 365 服务的 IP 地址范围和 URL 的所有记录。The endpoints web method returns all records for IP address ranges and URLs that make up the Office 365 service. 应始终使用最新的终结点 Web 方法数据来进行网络设备配置。The latest data from the endpoints web method should always be used for network device configuration. Microsoft 会在发布新增内容前 30 天提前发出通知,以便你有时间更新访问控制列表和代理服务器跳过列表。Microsoft provides advance notice 30 days prior to publishing new additions to give you time to update access control lists and proxy server bypass lists. 建议你仅在版本 Web 方法表示存在新的数据版本时才再次调用终结点 Web 方法。We recommend that you only call the endpoints web method again when the version web method indicates that a new version of the data is available.

终结点 Web 方法的参数如下:Parameters for the endpoints web method are:

  • ServiceAreas=<Common | Exchange | SharePoint | Skype> — 以逗号分隔的服务区域列表。ServiceAreas=<Common | Exchange | SharePoint | Skype> — A comma-separated list of service areas. 有效项为 CommonExchangeSharePointSkypeValid items are Common, Exchange, SharePoint, and Skype. 由于 Common 服务区域项为所有其他服务区域的先决条件,因此 Web 服务始终包括它们。Because Common service area items are a prerequisite for all other service areas, the web service always includes them. 如果不包括此参数,则会返回所有服务区域。If you do not include this parameter, all service areas are returned.
  • TenantName=<tenant_name> — 你的 Office 365 租户名称。TenantName=<tenant_name> — Your Office 365 tenant name. Web 服务采用所提供的名称,并将其插入到包含租户名称的 URL 中。The web service takes your provided name and inserts it in parts of URLs that include the tenant name. 如果未提供租户名称,则这些 URL 的部分具有通配符字符 (*)。If you don't provide a tenant name, those parts of URLs have the wildcard character (*).
  • NoIPv6=<true | false> — 将此值设置为 true 可从输出中排除 IPv6 地址(如果你未在网络中使用 IPv6)。NoIPv6=<true | false> — Set the value to true to exclude IPv6 addresses from the output if you don't use IPv6 in your network.
  • Instance=<Worldwide | China | Germany | USGovDoD | USGovGCCHigh> — 此必填参数用于指定从中返回终结点的实例。Instance=<Worldwide | China | Germany | USGovDoD | USGovGCCHigh> — This required parameter specifies the instance from which to return the endpoints. 有效实例包括:WorldwideChinaGermanyUSGovDoDUSGovGCCHighValid instances are: Worldwide, China, Germany, USGovDoD, and USGovGCCHigh.

如果从相同客户端 IP 地址调用终结点 Web 方法的次数过多,则可能会收到 HTTP 响应代码 429(请求过多)If you call the endpoints web method too many times from the same client IP address, you might receive HTTP response code 429 (Too Many Requests). 如果收到此响应代码,请先等待 1 小时,然后再重复你的请求,或者为该请求生成新的 GUID。If you get this response code, wait 1 hour before repeating your request, or generate a new GUID for the request. 作为一般的最佳实践,仅在版本 Web 方法表示存在新的可用版本时才调用终结点 Web 方法。As a general best practice, only call the endpoints web method when the version web method indicates that a new version is available.

终结点 Web 方法的结果是一组记录,每条记录均代表一个终结点集。The result from the endpoints web method is an array of records in which each record represents a specific endpoint set. 每条记录均包含以下元素:The elements for each record are:

  • id — 终结点集的不可变 ID 号。id — The immutable id number of the endpoint set.
  • serviceArea — 所属的服务区域:CommonExchangeSharePointSkypeserviceArea — The service area that this is part of: Common, Exchange, SharePoint, or Skype.
  • urls — 终结点集的 URL。urls — URLs for the endpoint set. 此为包含 DNS 记录的 JSON 数组。A JSON array of DNS records. 若为空白,将省略此元素。Omitted if blank.
  • tcpPorts — 终结点集的 TCP 端口。tcpPorts — TCP ports for the endpoint set. 所有端口元素都格式化为端口的逗号分隔列表,或用短划线字符 (-) 分隔的端口范围。All ports elements are formatted as a comma-separated list of ports or port ranges separated by a dash character (-). 端口适用于相应类别的特定终结点集中的所有 IP 地址和所有 URL。Ports apply to all IP addresses and all URLs in the endpoint set for a given category. 若为空白,将省略此元素。Omitted if blank.
  • udpPorts — 此终结点集中 IP 地址范围的 UDP 端口。udpPorts — UDP ports for the IP address ranges in this endpoint set. 若为空白,将省略此元素。Omitted if blank.
  • ips — 与此终结点关联的 IP 地址范围,设置为与列出的 TCP 或 UDP 端口关联。ips — The IP address ranges associated with this endpoint set as associated with the listed TCP or UDP ports. IP 地址范围的 JSON 数组。A JSON array of IP address ranges. 若为空白,将省略此元素。Omitted if blank.
  • category — 终结点集的连接类别。category — The connectivity category for the endpoint set. 有效值为 OptimizeAllowDefaultValid values are Optimize, Allow, and Default. 如果搜索特定 IP 地址或 URL 类别的终结点 Web 方法输出,则查询可能会返回多个类别。If you search the endpoints web method output for the category of a specific IP address or URL, it is possible that your query will return multiple categories. 在这种情况下,请按照最高优先级类别的建议操作。In such a case, follow the recommendation for the highest priority category. 例如,如果终结点同时显示在 OptimizeAllow 中,则应该遵循 Optimize 的要求。For example, if the endpoint appears in both Optimize and Allow, you should follow the requirements for Optimize. 必需项。Required.
  • expressRoute — 如果此终结点集通过 ExpressRoute 进行路由,则为 True,否则为 FalseexpressRoute — True if this endpoint set is routed over ExpressRoute, False if not.
  • required — 如果此终结点集必须有连接才能支持 Office 365,则为 Truerequired — True if this endpoint set is required to have connectivity for Office 365 to be supported. 如果此终结点集为可选,则为 FalseFalse if this endpoint set is optional.
  • notes — 对于可选终结点,此文本描述了无法在网络层访问此终结点集中的 IP 地址或 URL 的情况下不可用的 Office 365 功能。notes — For optional endpoints, this text describes Office 365 functionality that would be unavailable if IP addresses or URLs in this endpoint set cannot be accessed at the network layer. 若为空白,将省略此元素。Omitted if blank.

示例:Examples:

示例 1 请求 URI:https://endpoints.office.com/endpoints/Worldwide?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7Example 1 request URI: https://endpoints.office.com/endpoints/Worldwide?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7

此 URI 对全部工作负载获取 Office 365 全球实例的所有终结点。This URI obtains all endpoints for the Office 365 worldwide instance for all workloads. 示例结果的输出摘录如下:Example result that shows an excerpt of the output:

[
 {
  "id": 1,
  "serviceArea": "Exchange",
  "serviceAreaDisplayName": "Exchange Online",
  "urls":
   [
    "*.protection.outlook.com"
   ],
  "ips":
   [
    "2a01:111:f403::/48", "23.103.132.0/22", "23.103.136.0/21", "23.103.198.0/23", "23.103.212.0/22", "40.92.0.0/14", "40.107.0.0/17", "40.107.128.0/18", "52.100.0.0/14", "213.199.154.0/24", "213.199.180.128/26", "94.245.120.64/26", "207.46.163.0/24", "65.55.88.0/24", "216.32.180.0/23", "23.103.144.0/20", "65.55.169.0/24", "207.46.100.0/24", "2a01:111:f400:7c00::/54", "157.56.110.0/23", "23.103.200.0/22", "104.47.0.0/17", "2a01:111:f400:fc00::/54", "157.55.234.0/24", "157.56.112.0/24", "52.238.78.88/32"
   ],
  "tcpPorts": "443",
  "expressRoute": true,
  "category": "Allow"
 },
 {
  "id": 2,
  "serviceArea": "Exchange",
  "serviceAreaDisplayName": "Exchange Online",
  "urls":
   [
    "*.mail.protection.outlook.com"
   ],

请注意,此示例中的请求的完整输出将包含其他终结点集。Note that the full output of the request in this example would contain other endpoint sets.

示例 2 请求 URI:https://endpoints.office.com/endpoints/Worldwide?ServiceAreas=Exchange&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7Example 2 request URI: https://endpoints.office.com/endpoints/Worldwide?ServiceAreas=Exchange&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7

此示例仅对 Exchange Online 和依赖项获取 Office 365 全球实例的终结点。This example obtains endpoints for the Office 365 Worldwide instance for Exchange Online and dependencies only.

示例 2 的输出类似于示例 1,不同之处在于结果不包括 SharePoint Online 或 Skype for Business Online 终结点。The output for example 2 is similar to example 1 except that the results would not include endpoints for SharePoint Online or Skype for Business Online.

变更 Web 方法Changes web method

变更 Web 方法返回已发布的最新更新。这通常是上月的 IP 地址范围和 URL 变更。The changes web method returns the most recent updates that have been published, typically the previous month's changes to IP address ranges and URLs.

终结点数据的最重要变更是新 URL 或 IP 地址。The most critical changes to endpoints data are new URLs and IP addresses. 如果无法将 IP 地址添加到防火墙访问控制列表,或无法将 URL 添加到代理服务器跳过列表,可能会导致网络设备后的 Office 365 用户遇到服务中断。Failure to add an IP address to a firewall access control list or a URL to a proxy server bypass list can cause an outage for Office 365 users behind that network device. 尽管有运营要求,新的终结点将在其配置使用之日的前 30 天提前发布到 Web 服务,以便你有时间更新访问控制列表和代理服务器跳过列表。Notwithstanding operational requirements, new endpoints are published to the web service 30 days in advance of the date the endpoints are provisioned for use to give you time to update access control lists and proxy server bypass lists.

变更 Web 方法需要使用以下必填参数:The required parameter for the changes web method is:

  • Version=<YYYYMMDDNN> — 所需的 URL 路由参数。Version=<YYYYMMDDNN> — Required URL route parameter. 此值为当前实施的版本。This value is the version that you have currently implemented. Web 服务应返回自该版本之后发生的变更。The web service will return the changes since that version. 格式为 YYYYMMDDNN;如果需要在一天内发布多个版本,则 NN 是一个递增的自然数,而 00 表示给定日期的第一个更新。The format is YYYYMMDDNN, where NN is a natural number incremented if there are multiple versions required to be published on a single day, with 00 representing the first update for a given day. Web 服务要求 version 参数恰好包含 10 位数。The web service requires the version parameter to contain exactly 10 digits.

变更 Web 方法受速率限制,与终结点 Web 方法受限于速率一样。The changes web method is rate limited in the same way as the endpoints web method. 如果收到 429 HTTP 响应代码,请先等待 1 小时,然后再重复你的请求,或者为该请求生成新的 GUID。If you receive a 429 HTTP response code, wait 1 hour before repeating your request or generate a new GUID for the request.

变更 Web 方法的结果是一组记录,每条记录均代表特定版本终结点中的变更。The result from the changes web method is an array of records in which each record represents a change in a specific version of the endpoints. 每条记录均包含以下元素:The elements for each record are:

  • id — 变更记录的不可变 ID。id — The immutable id of the change record.
  • endpointSetId — 变更的终结点集记录的 ID。endpointSetId — The ID of the endpoint set record that is changed.
  • disposition — 描述了终结点集记录有何变更。disposition — Describes what the change did to the endpoint set record. 值包括 changeaddremoveValues are change, add, or remove.
  • impact — 并非所有变更都对每个环境同样重要。impact — Not all changes will be equally important to every environment. 此元素说明了相应变更对企业网络外围环境的预期影响。This element describes the expected impact to an enterprise network perimeter environment as a result of this change. 此属性仅包含在版本 2018112800 及更高版本的变更记录中。This element is included only in change records of version 2018112800 and later. impact 选项包括:— AddedIp – IP 地址已添加到 Office 365,且很快就会对服务生效。Options for the impact are: — AddedIp – An IP address was added to Office 365 and will be live on the service soon. 这表示需要更改防火墙或其他第 3 层网络外围设备。This represents a change you need to take on a firewall or other layer 3 network perimeter device. 如果你并没有在我们开始使用此元素之前添加它,可能会遇到故障。If you don’t add this before we start using it, you may experience an outage. — AddedUrl – URL 已添加到 Office 365,且很快就会对服务生效。— AddedUrl – A URL was added to Office 365 and will be live on the service soon. 这表示需要更改代理服务器或 URL 分析网络外围设备。This represents a change you need to take on a proxy server or URL parsing network perimeter device. 如果你并没有在我们开始使用之前添加此 URL,可能会遇到故障。If you don’t add this URL before we start using it, you may experience an outage. — AddedIpAndUrl — IP 地址和 URL 均已添加。— AddedIpAndUrl — Both an IP address and a URL were added. 这表示需要更改防火墙第 3 层设备、代理服务器或 URL 分析设备。This represents a change you need to take on either a firewall layer 3 device or a proxy server or URL parsing device. 如果你并没有在我们开始使用之前添加此 IP/URL,可能会遇到故障。If you don’t add this IP/URL pair before we start using it, you may experience an outage. — RemovedIpOrUrl – 从 Office 365 中至少删除了一个 IP 地址或 URL。— RemovedIpOrUrl – At least one IP address or URL was removed from Office 365. 从外围设备中删除网络终结点,但此操作并无截止时间。Remove the network endpoints from your perimeter devices, but there’s no deadline for you to do this. — ChangedIsExpressRoute – ExpressRoute 支持属性已更改。— ChangedIsExpressRoute – The ExpressRoute support attribute was changed. 如果使用 ExpressRoute,可能需要采取措施,具体视配置而定。If you use ExpressRoute, you might need to take action depending on your configuration. — MovedIpOrUrl – 在此终结点集和另一个终结点集之间迁移了 IP 地址或 URL。— MovedIpOrUrl – We moved an IP address or Url between this endpoint set and another one. 通常无需采取任何措施。Generally no action is required. — RemovedDuplicateIpOrUrl – 删除了重复的 IP 地址或 URL,但它仍是对 Office 365 发布的。— RemovedDuplicateIpOrUrl – We removed a duplicate IP address or Url but it’s still published for Office 365. 通常无需采取任何措施。Generally no action is required. — OtherNonPriorityChanges – 更改了一些不如其他所有选项重要的内容,例如注释字段的内容。— OtherNonPriorityChanges – We changed something less critical than all of the other options, such as the contents of a note field.
  • version — 引入变更的已发布终结点集的版本。version — The version of the published endpoint set in which the change was introduced. 版本号格式为 YYYYMMDDNN,其中 NN 是必须在一天内发布多个版本时递增的自然数。Version numbers are of the format YYYYMMDDNN, where NN is a natural number incremented if there are multiple versions required to be published on a single day.
  • previous — 详细说明终结点集上的旧变更元素值的子结构。previous — A substructure detailing previous values of changed elements on the endpoint set. 对于新添加的终结点集,它们未包含在内。This will not be included for newly added endpoint sets. 包括 ExpressRouteserviceAreacategoryrequiredtcpPortsudpPortsnotesIncludes ExpressRoute, serviceArea, category, required, tcpPorts, udpPorts, and notes.
  • current — 详细说明终结点集上的更新变更元素值的子结构。current — A substructure detailing updated values of changes elements on the endpoint set. 包括 ExpressRouteserviceAreacategoryrequiredtcpPortsudpPortsnotesIncludes ExpressRoute, serviceArea, category, required, tcpPorts, udpPorts, and notes.
  • add — 详细说明要添加到终结点集集合的项的子结构。add — A substructure detailing items to be added to endpoint set collections. 如果没有要添加的项,将省略此元素。Omitted if there are no additions. — effectiveDate — 定义添加项在服务中的生效日期。— effectiveDate — Defines the data when the additions will be live in the service. — ips — 要添加到 ips 数组的项。— ips — Items to be added to the ips array. — urls — 要添加到 urls 数组的项。— urls- Items to be added to the urls array.
  • remove — 详细说明要从终结点集中删除的项的子结构。remove — A substructure detailing items to be removed from the endpoint set. 如果没有删除项,则省略。Omitted if there are no removals. — ips — 要从 ips 数组中删除的项。— ips — Items to be removed from the ips array. — urls — 要从 urls 数组中删除的项。— urls- Items to be removed from the urls array.

示例:Examples:

示例 1 请求 URI:https://endpoints.office.com/changes/worldwide/0000000000?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7Example 1 request URI: https://endpoints.office.com/changes/worldwide/0000000000?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7

这请求获取 Office 365 全球服务实例先前的所有变更。示例结果如下:This requests all previous changes to the Office 365 worldwide service instance. Example result:

[
 {
  "id": 424,
  "endpointSetId": 32,
  "disposition": "Change",
  "version": "2018062700",
  "remove":
   {
    "urls":
     [
      "*.api.skype.com", "skypegraph.skype.com"
     ]
   }
 },
 {
  "id": 426,
  "endpointSetId": 31,
  "disposition": "Change",
  "version": "2018062700",
  "add":
   {
    "effectiveDate": "20180609",
    "ips":
     [
      "51.140.203.190/32"
     ]
   },
  "remove":
   {
    "ips":
     [

示例 2 请求 URI:https://endpoints.office.com/changes/worldwide/2018062700?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7Example 2 request URI: https://endpoints.office.com/changes/worldwide/2018062700?ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7

这请求获取 Office 365 全球实例自指定版本起的变更。在此示例中,指定版本是最新版本。示例结果如下:This requests changes since the specified version to the Office 365 Worldwide instance. In this case, the version specified is the latest. Example result:

[
  {
    "id":3,
    "endpointSetId":33,
    "changeDescription":"Removing old IP prefixes",
    "disposition":"Change",
    "version":"2018031301",
    "remove":{
      "ips":["65.55.127.0/24","66.119.157.192/26","66.119.158.0/25",
      "111.221.76.128/25","111.221.77.0/26","207.46.5.0/24"]
    }
  },
  {
    "id":4,
    "endpointSetId":45,
    "changeDescription":"Removing old IP prefixes",
    "disposition":"Change",
    "version":"2018031301",
    "remove":{
      "ips":["13.78.93.8/32","40.113.87.220/32","40.114.149.220/32",
      "40.117.100.83/32","40.118.214.164/32","104.208.31.113/32"]
    }
  }
]

示例 PowerShell 脚本Example PowerShell Script

你可以运行此 PowerShell 脚本来查看是否需要为更新的数据采取操作。You can run this PowerShell script to see if there are actions you need to take for updated data. 你可以将此脚本作为计划任务运行,以检查是否存在版本更新。You can run this script as a scheduled task to check for a version update. 为了避免 Web 服务出现过多负载,每小时运行脚本的次数不要超过一次。To avoid excessive load on the web service, try not to run the script more than once an hour.

此脚本执行以下操作:The script does the following:

  • 通过调用 Web 服务 REST API,检查 Office 365 全球实例终结点的版本号。Checks the version number of the current Office 365 Worldwide instance endpoints by calling the web service REST API.

  • 检查 $Env:TEMP\O365_endpoints_latestversion.txt 中的当前版本文件。Checks for a current version file at $Env:TEMP\O365_endpoints_latestversion.txt. 全局变量 $Env:TEMP 的路径通常为 C:\Users\<username>\AppData\Local\TempThe path of the global variable $Env:TEMP is usually C:\Users\<username>\AppData\Local\Temp.

  • 如果这是首次运行脚本,则脚本将返回当前版本以及所有当前 IP 地址和 URL,将终结点版本写入文件 $Env:TEMP\O365_endpoints_latestversion.txt,并将终结点数据输出写入文件 $Env:TEMP\O365_endpoints_data.txtIf this is the first time the script has been run, the script returns the current version and all current IP addresses and URLs, writes the endpoints version to the file $Env:TEMP\O365_endpoints_latestversion.txt and the endpoints data output to the file $Env:TEMP\O365_endpoints_data.txt. 可通过编辑以下行来修改输出文件的路径和/或名称:You can modify the path and/or name of the output file by editing these lines:

    $versionpath = $Env:TEMP + "\O365_endpoints_latestversion.txt"
    $datapath = $Env:TEMP + "\O365_endpoints_data.txt"
    
  • 在后续每次执行脚本时,如果最新的 Web 服务版本与 O365_endpoints_latestversion.txt 文件中的版本相同,则脚本将退出,而不进行任何更改。On each subsequent execution of the script, if the latest web service version is identical to the version in the O365_endpoints_latestversion.txt file, the script exits without making any changes.

  • 如果最新的 Web 服务版本比 O365_endpoints_latestversion.txt 文件中的版本更新,则该脚本将返回 AllowOptimize 类别的终结点和筛选器,更新 O365_endpoints_latestversion.txt 文件中的版本,并将更新的数据写入 O365_endpoints_data.txt 文件。When the latest web service version is newer than the version in the O365_endpoints_latestversion.txt file, the script returns the endpoints and filters for the Allow and Optimize category endpoints, updates the version in the O365_endpoints_latestversion.txt file, and writes the updated data to the O365_endpoints_data.txt file.

该脚本将为在其上运行的计算机生成唯一的 ClientRequestId,并在多个调用中重复使用此 ID。The script generates a unique ClientRequestId for the computer it is executed on, and reuses this ID across multiple calls. 此 ID 存储在 O365_endpoints_latestversion.txt 文件中。This ID is stored in the O365_endpoints_latestversion.txt file.

运行 PowerShell 脚本To run the PowerShell script

  1. 复制脚本并在本地硬盘驱动器或脚本位置将其另存为 Get-O365WebServiceUpdates.ps1Copy the script and save it to your local hard drive or script location as Get-O365WebServiceUpdates.ps1.

  2. 在首选脚本编辑器(如 PowerShell ISE 或 VS Code)中执行脚本,或使用以下命令从 PowerShell 控制台执行:Execute the script in your preferred script editor such as the PowerShell ISE or VS Code, or from a PowerShell console using the following command:

    powershell.exe -file <path>\Get-O365WebServiceUpdates.ps1
    

    不向脚本传递任何参数。There are no parameters to pass to the script.

<# Get-O365WebServiceUpdates.ps1
From https://aka.ms/ipurlws
v1.1 8/6/2019

DESCRIPTION
This script calls the REST API of the Office 365 IP and URL Web Service (Worldwide instance)
and checks to see if there has been a new update since the version stored in an existing
$Env:TEMP\O365_endpoints_latestversion.txt file in your user directory's temp folder
(usually C:\Users\<username>\AppData\Local\Temp).
If the file doesn't exist, or the latest version is newer than the current version in the
file, the script returns IPs and/or URLs that have been changed, added or removed in the latest
update and writes the new version and data to the output file $Env:TEMP\O365_endpoints_data.txt.

USAGE
Run as a scheduled task every 60 minutes.

PARAMETERS
n/a

PREREQUISITES
PS script execution policy: Bypass
PowerShell 3.0 or later
Does not require elevation
#>

#Requires -Version 3.0

# web service root URL
$ws = "https://endpoints.office.com"
# path where output files will be stored
$versionpath = $Env:TEMP + "\O365_endpoints_latestversion.txt"
$datapath = $Env:TEMP + "\O365_endpoints_data.txt"

# fetch client ID and version if version file exists; otherwise create new file and client ID
if (Test-Path $versionpath) {
    $content = Get-Content $versionpath
    $clientRequestId = $content[0]
    $lastVersion = $content[1]
    Write-Output ("Version file exists! Current version: " + $lastVersion)
}
else {
    Write-Output ("First run! Creating version file at " + $versionpath + ".")
    $clientRequestId = [GUID]::NewGuid().Guid
    $lastVersion = "0000000000"
    @($clientRequestId, $lastVersion) | Out-File $versionpath
}

# call version method to check the latest version, and pull new data if version number is different
$version = Invoke-RestMethod -Uri ($ws + "/version/Worldwide?clientRequestId=" + $clientRequestId)
if ($version.latest -gt $lastVersion) {
    Write-Host "New version of Office 365 worldwide commercial service instance endpoints detected"
    # write the new version number to the version file
    @($clientRequestId, $version.latest) | Out-File $versionpath
    # invoke endpoints method to get the new data
    $endpointSets = Invoke-RestMethod -Uri ($ws + "/endpoints/Worldwide?clientRequestId=" + $clientRequestId)
    # filter results for Allow and Optimize endpoints, and transform these into custom objects with port and category
    # URL results
    $flatUrls = $endpointSets | ForEach-Object {
        $endpointSet = $_
        $urls = $(if ($endpointSet.urls.Count -gt 0) { $endpointSet.urls } else { @() })
        $urlCustomObjects = @()
        if ($endpointSet.category -in ("Allow", "Optimize")) {
            $urlCustomObjects = $urls | ForEach-Object {
                [PSCustomObject]@{
                    category = $endpointSet.category;
                    url      = $_;
                    tcpPorts = $endpointSet.tcpPorts;
                    udpPorts = $endpointSet.udpPorts;
                }
            }
        }
        $urlCustomObjects
    }
    # IPv4 results
    $flatIp4s = $endpointSets | ForEach-Object {
        $endpointSet = $_
        $ips = $(if ($endpointSet.ips.Count -gt 0) { $endpointSet.ips } else { @() })
        # IPv4 strings contain dots
        $ip4s = $ips | Where-Object { $_ -like '*.*' }
        $ip4CustomObjects = @()
        if ($endpointSet.category -in ("Allow", "Optimize")) {
            $ip4CustomObjects = $ip4s | ForEach-Object {
                [PSCustomObject]@{
                    category = $endpointSet.category;
                    ip = $_;
                    tcpPorts = $endpointSet.tcpPorts;
                    udpPorts = $endpointSet.udpPorts;
                }
            }
        }
        $ip4CustomObjects
    }
    # IPv6 results
    $flatIp6s = $endpointSets | ForEach-Object {
        $endpointSet = $_
        $ips = $(if ($endpointSet.ips.Count -gt 0) { $endpointSet.ips } else { @() })
        # IPv6 strings contain colons
        $ip6s = $ips | Where-Object { $_ -like '*:*' }
        $ip6CustomObjects = @()
        if ($endpointSet.category -in ("Optimize")) {
            $ip6CustomObjects = $ip6s | ForEach-Object {
                [PSCustomObject]@{
                    category = $endpointSet.category;
                    ip = $_;
                    tcpPorts = $endpointSet.tcpPorts;
                    udpPorts = $endpointSet.udpPorts;
                }
            }
        }
        $ip6CustomObjects
    }

    # write output to screen
    Write-Output ("Client Request ID: " + $clientRequestId)
    Write-Output ("Last Version: " + $lastVersion)
    Write-Output ("New Version: " + $version.latest)
    Write-Output ""
    Write-Output "IPv4 Firewall IP Address Ranges"
    ($flatIp4s.ip | Sort-Object -Unique) -join "," | Out-String
    Write-Output "IPv6 Firewall IP Address Ranges"
    ($flatIp6s.ip | Sort-Object -Unique) -join "," | Out-String
    Write-Output "URLs for Proxy Server"
    ($flatUrls.url | Sort-Object -Unique) -join "," | Out-String
    Write-Output ("IP and URL data written to " + $datapath)

    # write output to data file
    Write-Output "Office 365 IP and UL Web Service data" | Out-File $datapath
    Write-Output "Worldwide instance" | Out-File $datapath -Append
    Write-Output "" | Out-File $datapath -Append
    Write-Output ("Version: " + $version.latest) | Out-File $datapath -Append
    Write-Output "" | Out-File $datapath -Append
    Write-Output "IPv4 Firewall IP Address Ranges" | Out-File $datapath -Append
    ($flatIp4s.ip | Sort-Object -Unique) -join "," | Out-File $datapath -Append
    Write-Output "" | Out-File $datapath -Append
    Write-Output "IPv6 Firewall IP Address Ranges" | Out-File $datapath -Append
    ($flatIp6s.ip | Sort-Object -Unique) -join "," | Out-File $datapath -Append
    Write-Output "" | Out-File $datapath -Append
    Write-Output "URLs for Proxy Server" | Out-File $datapath -Append
    ($flatUrls.url | Sort-Object -Unique) -join "," | Out-File $datapath -Append
}
else {
    Write-Host "Office 365 worldwide commercial service instance endpoints are up-to-date."
}

示例 Python 脚本Example Python Script

运行下面的 Python 脚本(已使用 Windows 10 上的 Python 3.6.3 进行测试),可确定是否需要对已更新数据执行操作。此脚本检查 Office 365 全球实例终结点的版本号。若有变更,它就会下载终结点,并筛选出 AllowOptimize 类别终结点。它还会跨多个调用使用唯一 ClientRequestId,并将找到的最新版本保存到临时文件中。应每小时调用一次此脚本,以检查是否有版本更新。Here is a Python script, tested with Python 3.6.3 on Windows 10, that you can run to see if there are actions you need to take for updated data. This script checks the version number for the Office 365 Worldwide instance endpoints. When there is a change, it downloads the endpoints and filters for the Allow and Optimize category endpoints. It also uses a unique ClientRequestId across multiple calls and saves the latest version found in a temporary file. You should call this script once an hour to check for a version update.

import json
import tempfile
from pathlib import Path
import urllib.request
import uuid
# helper to call the webservice and parse the response
def webApiGet(methodName, instanceName, clientRequestId):
    ws = "https://endpoints.office.com"
    requestPath = ws + '/' + methodName + '/' + instanceName + '?clientRequestId=' + clientRequestId
    request = urllib.request.Request(requestPath)
    with urllib.request.urlopen(request) as response:
        return json.loads(response.read().decode())
# path where client ID and latest version number will be stored
datapath = Path(tempfile.gettempdir() + '/endpoints_clientid_latestversion.txt')
# fetch client ID and version if data exists; otherwise create new file
if datapath.exists():
    with open(datapath, 'r') as fin:
        clientRequestId = fin.readline().strip()
        latestVersion = fin.readline().strip()
else:
    clientRequestId = str(uuid.uuid4())
    latestVersion = '0000000000'
    with open(datapath, 'w') as fout:
        fout.write(clientRequestId + '\n' + latestVersion)
# call version method to check the latest version, and pull new data if version number is different
version = webApiGet('version', 'Worldwide', clientRequestId)
if version['latest'] > latestVersion:
    print('New version of Office 365 worldwide commercial service instance endpoints detected')
    # write the new version number to the data file
    with open(datapath, 'w') as fout:
        fout.write(clientRequestId + '\n' + version['latest'])
    # invoke endpoints method to get the new data
    endpointSets = webApiGet('endpoints', 'Worldwide', clientRequestId)
    # filter results for Allow and Optimize endpoints, and transform these into tuples with port and category
    flatUrls = []
    for endpointSet in endpointSets:
        if endpointSet['category'] in ('Optimize', 'Allow'):
            category = endpointSet['category']
            urls = endpointSet['urls'] if 'urls' in endpointSet else []
            tcpPorts = endpointSet['tcpPorts'] if 'tcpPorts' in endpointSet else ''
            udpPorts = endpointSet['udpPorts'] if 'udpPorts' in endpointSet else ''
            flatUrls.extend([(category, url, tcpPorts, udpPorts) for url in urls])
    flatIps = []
    for endpointSet in endpointSets:
        if endpointSet['category'] in ('Optimize', 'Allow'):
            ips = endpointSet['ips'] if 'ips' in endpointSet else []
            category = endpointSet['category']
            # IPv4 strings have dots while IPv6 strings have colons
            ip4s = [ip for ip in ips if '.' in ip]
            tcpPorts = endpointSet['tcpPorts'] if 'tcpPorts' in endpointSet else ''
            udpPorts = endpointSet['udpPorts'] if 'udpPorts' in endpointSet else ''
            flatIps.extend([(category, ip, tcpPorts, udpPorts) for ip in ip4s])
    print('IPv4 Firewall IP Address Ranges')
    print(','.join(sorted(set([ip for (category, ip, tcpPorts, udpPorts) in flatIps]))))
    print('URLs for Proxy Server')
    print(','.join(sorted(set([url for (category, url, tcpPorts, udpPorts) in flatUrls]))))

    # TODO send mail (e.g. with smtplib/email modules) with new endpoints data
else:
    print('Office 365 worldwide commercial service instance endpoints are up-to-date')

Web 服务接口版本控制Web Service interface versioning

日后可能需要更新这些 Web 服务方法的参数或结果。Updates to the parameters or results for these web service methods may be required in the future. 在这些 Web 服务的正式版本发布后,Microsoft 将做出合理的努力,以事先通知 Web 服务的实质性更新。After the general availability version of these web services is published, Microsoft will make reasonable efforts to provide advance notice of material updates to the web service. 如果认为更新必须变更使用 Web 服务的客户端,Microsoft 将在新版本发布后的至少 12 个月内保留旧版(上一版)Web 服务。When Microsoft believes that an update will require changes to clients using the web service, Microsoft will keep the previous version (one version back) of the web service available for at least 12 months after the release of the new version. 在此期间未升级的客户可能无法访问 Web 服务及其方法。Customers who do not upgrade during that time may be unable to access the web service and its methods. 如果 Web 服务接口签名发生以下变更,客户必须确保 Web 服务的客户端能继续正常运行,而不出现错误:Customers must ensure that clients of the web service continue working without error if the following changes are made to the web service interface signature:

  • 将新的可选参数添加到现有 Web 方法中,此参数既不必由旧客户端提供,也不会影响旧客户端收到的结果。Adding a new optional parameter to an existing web method that doesn't have to be provided by older clients and doesn't impact the result an older client receives.
  • 将响应 REST 项之一或其他列中的新命名特性添加到响应 CSV。Adding a new named attribute in one of the response REST items or additional columns to the response CSV.
  • 添加新 Web 方法,其使用旧客户端未调用的新名称。Adding a new web method with a new name that is not called by the older clients.

更新通知Update notifications

当 IP 地址和 URL 的变更发布到 Web 服务时,你可以使用几种不同的方法来获取电子邮件通知。You can use a few different methods to get email notifications when changes to the IP addresses and URLs are published to the web service.

导出代理 PAC 文件Exporting a Proxy PAC file

Get-PacFile 是 PowerShell 脚本,它从 Office 365 IP 地址和 URL Web 服务读取最新网络终结点,并创建示例 PAC 文件。Get-PacFile is a PowerShell script that reads the latest network endpoints from the Office 365 IP Address and URL web service and creates a sample PAC file. 有关使用 Get-PacFile 的信息,请参阅使用 PAC 文件进行至关重要的 Office 365 流量的直接路由For information on using Get-PacFile, see Use a PAC file for direct routing of vital Office 365 traffic.

Office 365 URL 和 IP 地址范围Office 365 URLs and IP address ranges

管理 Office 365 终结点Managing Office 365 endpoints

Office 365 终结点 FAQOffice 365 endpoints FAQ

Office 365 网络连接原则Office 365 Network Connectivity Principles

Office 365 网络和性能优化Office 365 network and performance tuning

评估 Office 365 网络连接Assessing Office 365 network connectivity

Skype for Business Online 中的媒体质量和网络连接性能Media Quality and Network Connectivity Performance in Skype for Business Online

优化 Skype for Business Online 网络Optimizing your network for Skype for Business Online

使用基线和性能历史记录优化 Office 365 性能Office 365 performance tuning using baselines and performance history

Office 365 性能疑难解答计划Performance troubleshooting plan for Office 365