Microsoft 365 endpoint publication contract
Microsoft's edit ·
Microsoft's commit message in MicrosoftDocs/microsoft-365-docs · commit cd97931 · +49 −49 lines · also on GitHub
⋯ 29 unchanged lines
3030
3131
# Microsoft 365 IP Address and URL web service
3232
33
−The Microsoft 365 IP Address and URL web service helps you better identify and differentiate Microsoft 365 network traffic, making it easier for you to evaluate, configure, and stay up to date with changes. This REST-based web service replaces the previous XML downloadable files, which were phased out on October 2, 2018.
33
+The Microsoft 365 IP Address and URL web service help you better identify and differentiate Microsoft 365 network traffic, making it easier for you to evaluate, configure, and stay up to date with changes. This REST-based web service replaces the previous XML downloadable files, which were phased out on October 2, 2018.
3434
3535
As a customer or a network perimeter device vendor, you can build against the web service for Microsoft 365 IP address and FQDN entries. You can access the data directly in a web browser using these URLs:
3636
⋯ 12 unchanged lines
4949
- Get the current changes.
5050
5151
> [!NOTE]
52
−> If you're using Azure ExpressRoute to connect to Microsoft 365, review [Azure ExpressRoute for Microsoft 365](azure-expressroute.md) to familiarize yourself with the Microsoft 365 services supported over Azure ExpressRoute. Also review the article [Microsoft 365 URLs and IP address ranges](urls-and-ip-address-ranges.md) to understand which network requests for Microsoft 365 applications require Internet connectivity. This will help to better configure your perimeter security devices.
52
+> If you're using Azure ExpressRoute to connect to Microsoft 365, review [Azure ExpressRoute for Microsoft 365](azure-expressroute.md) to familiarize yourself with the Microsoft 365 services supported over Azure ExpressRoute. Also review the article [Microsoft 365 URLs and IP address ranges](urls-and-ip-address-ranges.md) to understand which network requests for Microsoft 365 applications require Internet connectivity. This helps to better configure your perimeter security devices.
5353
5454
For more information, see:
5555
⋯ 4 unchanged lines
6060
6161
These parameters are common across all the web service methods:
6262
63
−- **format=\<JSON \| CSV\>** —By default, the returned data format is JSON. Use this optional parameter to return the data in comma-separated values (CSV) format.
64
−- **ClientRequestId=\<guid\>** —A required GUID that you generate for client association. Generate a unique GUID for each machine that calls the web service (the scripts included on this page generate a GUID for you). Don't use the GUIDs shown in the following examples because they might be blocked by the web service in the future. GUID format is `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, where x represents a hexadecimal number.
63
+- **format=\<JSON \| CSV\>** - By default, the returned data format is JSON. Use this optional parameter to return the data in comma-separated values (CSV) format.
64
+- **ClientRequestId=\<guid\>** - A required GUID that you generate for client association. Generate a unique GUID for each machine that calls the web service (the scripts included on this page generate a GUID for you). Don't use the GUIDs shown in the following examples because they might be blocked by the web service in the future. GUID format is `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, where x represents a hexadecimal number.
6565
6666
To generate a GUID, you can use the [New-Guid](/powershell/module/microsoft.powershell.utility/new-guid) PowerShell command, or use an online service such as [Online GUID Generator](https://www.guidgenerator.com/).
6767
6868
## Version web method
6969
70
−Microsoft updates the Microsoft 365 IP address and FQDN entries at the beginning of each month. Out-of-band updates are sometimes published due to support incidents, security updates or other operational requirements.
70
+Microsoft updates the Microsoft 365 IP address and FQDN entries at the beginning of each month. Out-of-band updates are sometimes published due to support incidents, security updates, or other operational requirements.
7171
7272
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 Microsoft 365 service instance. We recommend that you check the version not more than once an hour.
7373
7474
Parameters for the version web method are:
7575
76
−- **AllVersions=\<true \| false\>** —By default, the version returned is the latest. Include this optional parameter to request all published versions since the web service was first released.
77
−- **Format=\<JSON \| CSV \| RSS\>** —In addition to the JSON and CSV formats, the version web method also supports 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.
78
−- **Instance=\<Worldwide \| China \| USGovDoD \| USGovGCCHigh\>** —This optional parameter specifies the instance to return the version for. If omitted, all instances are returned. Valid instances are: Worldwide, China, USGovDoD, USGovGCCHigh.
76
+- **AllVersions=\<true \| false\>** - By default, the version returned is the latest. Include this optional parameter to request all published versions since the web service was first released.
77
+- **Format=\<JSON \| CSV \| RSS\>** - In addition to the JSON and CSV formats, the version web method also supports 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.
78
+- **Instance=\<Worldwide \| China \| USGovDoD \| USGovGCCHigh\>** - This optional parameter specifies the instance to return the version for. If omitted, all instances are returned. Valid instances are: Worldwide, China, USGovDoD, USGovGCCHigh.
7979
8080
The version web method isn't rate limited and doesn't ever return 429 HTTP Response Codes. The response to the version web method does include a cache-control header recommending caching of the data for 1 hour. The result from the version web method can be a single record or an array of records. The elements of each record are:
8181
82
−- instance—The short name of the Microsoft 365 service instance.
83
−- latest—The latest version for endpoints of the specified instance.
84
−- versions—A list of all previous versions for the specified instance. This element is only included if the `AllVersions` parameter is true.
82
+- `instance` - The short name of the Microsoft 365 service instance.
83
+- `latest` - The latest version for endpoints of the specified instance.
84
+- `versions` - A list of all previous versions for the specified instance. This element is only included if the `AllVersions` parameter is true.
8585
8686
### Version web method examples
8787
⋯ 85 unchanged lines
173173
174174
Parameters for the endpoints web method are:
175175
176
−- **ServiceAreas=\<Common \| Exchange \| SharePoint \| Skype\>** —A comma-separated list of service areas. Valid items are `Common`, `Exchange`, `SharePoint`, and `Skype`. Because `Common` service area items are a prerequisite for all other service areas, the web service always includes them. If you don't include this parameter, all service areas are returned.
177
−- **TenantName=\<tenant_name\>** —Your Microsoft 365 tenant name. The web service takes your provided name and inserts it in parts of URLs that include the tenant name. If you don't provide a tenant name, those parts of URLs have the wildcard character (\*).
178
−- **NoIPv6=\<true \| false\>** —Set the value to `true` to exclude IPv6 addresses from the output if you don't use IPv6 in your network.
179
−- **Instance=\<Worldwide \| China \| USGovDoD \| USGovGCCHigh\>** —This required parameter specifies the instance from which to return the endpoints. Valid instances are: `Worldwide`, `China`, `USGovDoD`, and `USGovGCCHigh`.
176
+- **ServiceAreas=\<Common \| Exchange \| SharePoint \| Skype\>** - A comma-separated list of service areas. Valid items are `Common`, `Exchange`, `SharePoint`, and `Skype`. Because `Common` service area items are a prerequisite for all other service areas, the web service always includes them. If you don't include this parameter, all service areas are returned.
177
+- **TenantName=\<tenant_name\>** - Your Microsoft 365 tenant name. The web service takes your provided name and inserts it in parts of URLs that include the tenant name. If you don't provide a tenant name, those parts of URLs have the wildcard character (\*).
178
+- **NoIPv6=\<true \| false\>** - Set the value to `true` to exclude IPv6 addresses from the output if you don't use IPv6 in your network.
179
+- **Instance=\<Worldwide \| China \| USGovDoD \| USGovGCCHigh\>** - This required parameter specifies the instance from which to return the endpoints. Valid instances are: `Worldwide`, `China`, `USGovDoD`, and `USGovGCCHigh`.
180180
181181
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)`. If you get this response code, wait 1 hour before repeating your request, or generate a new GUID for the request. As a general best practice, only call the endpoints web method when the version web method indicates that a new version is available.
182182
183183
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:
184184
185
−- **id** —The immutable ID number of the endpoint set.
186
−- **serviceArea** —The service area that this is part of: `Common`, `Exchange`, `SharePoint`, or `Skype`.
187
−- **urls** —URLs for the endpoint set. A JSON array of DNS records. Omitted if blank.
188
−- **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 (-). Ports apply to all IP addresses and all URLs in the endpoint set for a given category. Omitted if blank.
189
−- **udpPorts**—UDP ports for the IP address ranges in this endpoint set. Omitted if blank.
190
−- **ips** —The IP address ranges associated with this endpoint set as associated with the listed TCP or UDP ports. A JSON array of IP address ranges. Omitted if blank.
191
−- **category** —The connectivity category for the endpoint set. Valid values are `Optimize`, `Allow`, and `Default`. If you search the endpoints web method output for the category of a specific IP address or URL, it's possible that your query will return multiple categories. In such a case, follow the recommendation for the highest priority category. For example, if the endpoint appears in both `Optimize` and `Allow`, you should follow the requirements for `Optimize`. Required.
192
−- **expressRoute** — `True` if this endpoint set is routed over ExpressRoute, `False` if not.
193
−- **required** — `True` if this endpoint set is required to have connectivity for Microsoft 365 to be supported. `False` if this endpoint set is optional.
194
−- **notes**—For optional endpoints, this text describes Microsoft 365 functionality that would be unavailable if IP addresses or URLs in this endpoint set can't be accessed at the network layer. Omitted if blank.
185
+- **id** - The immutable ID number of the endpoint set.
186
+- **serviceArea** - The service area that this is part of: `Common`, `Exchange`, `SharePoint`, or `Skype`.
187
+- **urls** - URLs for the endpoint set. A JSON array of DNS records. Omitted if blank.
188
+- **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 (-). Ports apply to all IP addresses and all URLs in the endpoint set for a given category. Omitted if blank.
189
+- **udpPorts** - UDP ports for the IP address ranges in this endpoint set. Omitted if blank.
190
+- **ips** - The IP address ranges associated with this endpoint set as associated with the listed TCP or UDP ports. A JSON array of IP address ranges. Omitted if blank.
191
+- **category** - The connectivity category for the endpoint set. Valid values are `Optimize`, `Allow`, and `Default`. If you search the endpoints web method output for the category of a specific IP address or URL, it's possible that your query will return multiple categories. In such a case, follow the recommendation for the highest priority category. For example, if the endpoint appears in both `Optimize` and `Allow`, you should follow the requirements for `Optimize`. Required.
192
+- **expressRoute** - `True` if this endpoint set is routed over ExpressRoute, `False` if not.
193
+- **required** - `True` if this endpoint set is required to have connectivity for Microsoft 365 to be supported. `False` if this endpoint set is optional.
194
+- **notes** - For optional endpoints, this text describes Microsoft 365 functionality that would be unavailable if IP addresses or URLs in this endpoint set can't be accessed at the network layer. Omitted if blank.
195195
196196
### Endpoints web method examples
197197
⋯ 45 unchanged lines
243243
244244
The required parameter for the changes web method is:
245245
246
−- **Version=\<YYYYMMDDNN>** —Required URL route parameter. This value is the version that you have currently implemented. The web service will return the changes since that version. 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. The web service requires the `version` parameter to contain exactly 10 digits.
246
+- **Version=\<YYYYMMDDNN>** - Required URL route parameter. This value is the version that you have currently implemented. The web service will return the changes since that version. 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. The web service requires the `version` parameter to contain exactly 10 digits.
247247
248248
The changes web method is rate limited in the same way as the endpoints web method. If you receive a 429 HTTP response code, wait 1 hour before repeating your request or generate a new GUID for the request.
249249
250250
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:
251251
252
−- id—The immutable ID of the change record.
253
−- endpointSetId—The ID of the endpoint set record that is changed.
254
−- disposition—Describes what the change did to the endpoint set record. Values are `change`, `add`, or `remove`.
255
−- 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. This element is included only in change records of version **2018112800** and later. Options for the impact are:
256
− - AddedIp – An IP address was added to Microsoft 365 and will be live on the service soon. 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 might experience an outage.
257
− - AddedUrl – A URL was added to Microsoft 365 and will be live on the service soon. This represents a change you need to take on a proxy server or URL parsing network perimeter device. If you don't add this URL before we start using it, you might experience an outage.
258
− - AddedIpAndUrl—Both an IP address and a URL were added. This represents a change you need to take on either a firewall layer 3 device or a proxy server or URL parsing device. If you don't add this IP/URL pair before we start using it, you might experience an outage.
259
− - AddedSubstituteUrl – An FQDN previously unpublished due to a wildcard is now published because the wildcard URL was removed. This change is effective immediately.
260
− - RemovedIpOrUrl – At least one IP address or URL was removed from Microsoft 365. Remove the network endpoints from your perimeter devices, but there's no deadline for you to do this.
261
− - ChangedIsExpressRoute – The ExpressRoute support attribute was changed. If you use ExpressRoute, you might need to take action depending on your configuration.
262
− - MovedIpOrUrl – We moved an IP address or Url between this endpoint set and another one. Generally no action is required.
263
− - RemovedDuplicateIpOrUrl – We removed a duplicate IP address or Url but it's still published for Microsoft 365. Generally no action is required.
264
− - OtherNonPriorityChanges – We changed something less critical than all of the other options, such as the contents of a note field.
265
−- version—The version of the published endpoint set in which the change was introduced. 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.
266
−- previous—A substructure detailing previous values of changed elements on the endpoint set. This won't be included for newly added endpoint sets. Includes `ExpressRoute`, `serviceArea`, `category`, `required`, `tcpPorts`, `udpPorts`, and `notes`.
267
−- current—A substructure detailing updated values of changes elements on the endpoint set. Includes `ExpressRoute`, `serviceArea`, `category`, `required`, `tcpPorts`, `udpPorts`, and `notes`.
268
−- add —A substructure detailing items to be added to endpoint set collections. Omitted if there are no additions.
269
− — effectiveDate—Defines the data when the additions will be live in the service.
270
− — ips—Items to be added to the `ips` array.
271
− — urls- Items to be added to the `urls` array.
272
−- remove—A substructure detailing items to be removed from the endpoint set. Omitted if there are no removals.
273
− — ips—Items to be removed from the `ips` array.
274
− — urls- Items to be removed from the `urls` array.
252
+- `id` - The immutable ID of the change record.
253
+- `endpointSetId` - The ID of the endpoint set record that is changed.
254
+- `disposition`- Describes what the change did to the endpoint set record. Values are `change`, `add`, or `remove`.
255
+- `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. This element is included only in change records of version **2018112800** and later. Options for the impact are:
256
+ - `AddedIp` - An IP address was added to Microsoft 365 and will be live on the service soon. 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 might experience an outage.
257
+ - `AddedUrl` - A URL was added to Microsoft 365 and will be live on the service soon. This represents a change you need to take on a proxy server or URL parsing network perimeter device. If you don't add this URL before we start using it, you might experience an outage.
258
+ - `AddedIpAndUrl` - Both an IP address and a URL were added. This represents a change you need to take on either a firewall layer 3 device or a proxy server or URL parsing device. If you don't add this IP/URL pair before we start using it, you might experience an outage.
259
+ - `AddedSubstituteUrl` - An FQDN previously unpublished due to a wildcard is now published because the wildcard URL was removed. This change is effective immediately.
260
+ - `RemovedIpOrUrl` - At least one IP address or URL was removed from Microsoft 365. Remove the network endpoints from your perimeter devices, but there's no deadline for you to do this.
261
+ - `ChangedIsExpressRoute` - The ExpressRoute support attribute was changed. If you use ExpressRoute, you might need to take action depending on your configuration.
262
+ - `MovedIpOrUrl` - We moved an IP address or Url between this endpoint set and another one. Generally no action is required.
263
+ - `RemovedDuplicateIpOrUrl` - We removed a duplicate IP address or Url but it's still published for Microsoft 365. Generally no action is required.
264
+ - `OtherNonPriorityChanges` - We changed something less critical than all of the other options, such as the contents of a note field.
265
+- `version` - The version of the published endpoint set in which the change was introduced. 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.
266
+- `previous` - A substructure detailing previous values of changed elements on the endpoint set. This won't be included for newly added endpoint sets. Includes `ExpressRoute`, `serviceArea`, `category`, `required`, `tcpPorts`, `udpPorts`, and `notes`.
267
+- `current`- A substructure detailing updated values of changes elements on the endpoint set. Includes `ExpressRoute`, `serviceArea`, `category`, `required`, `tcpPorts`, `udpPorts`, and `notes`.
268
+- `add` - A substructure detailing items to be added to endpoint set collections. Omitted if there are no additions.
269
+ - `effectiveDate` - Defines the data when the additions will be live in the service.
270
+ - `ips` - Items to be added to the `ips` array.
271
+ - `urls` - Items to be added to the `urls` array.
272
+- `remove` - A substructure detailing items to be removed from the endpoint set. Omitted if there are no removals.
273
+ - `ips` - Items to be removed from the `ips` array.
274
+ - `urls` - Items to be removed from the `urls` array.
275275
276276
### Changes web method examples
277277
⋯ 343 unchanged lines
Microsoft's Markdown source from MicrosoftDocs/microsoft-365-docs, © Microsoft Corporation, under CC BY 4.0. Changed lines with up to 3 unchanged lines around each; ChangeIntel kept this copy 10 Oct 05:18 UTC. The commit date is when the source changed, which can be hours or days before Learn published it.