Microsoft 365 endpoint publication contract
Microsoft's edit ·
Microsoft's commit message in MicrosoftDocs/microsoft-365-docs · commit cc53103 · +42 −52 lines · also on GitHub
⋯ 33 unchanged lines
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
37
−- For the latest version of the Microsoft 365 URLs and IP address ranges, use [https://endpoints.office.com/version](https://endpoints.office.com/version?clientrequestid=b10c5ed1-bad1-445f-b386-b919946339a7).
38
−- For the data on the Microsoft 365 URLs and IP address ranges page for firewalls and proxy servers, use [https://endpoints.office.com/endpoints/worldwide](https://endpoints.office.com/endpoints/worldwide?clientrequestid=b10c5ed1-bad1-445f-b386-b919946339a7).
39
−- To get all the latest changes since July 2018 when the web service was first available, use [https://endpoints.office.com/changes/worldwide/0000000000](https://endpoints.office.com/changes/worldwide/0000000000?clientrequestid=b10c5ed1-bad1-445f-b386-b919946339a7).
37
+- For the data on the Microsoft 365 URLs and IP address ranges page for firewalls and proxy servers, use [`https://endpoints.office.com/endpoints/worldwide`](https://endpoints.office.com/endpoints/worldwide?clientrequestid=b10c5ed1-bad1-445f-b386-b919946339a7).
38
+- To get all the latest changes since July 2018 when the web service was first available, use [`https://endpoints.office.com/changes/worldwide/0000000000`](https://endpoints.office.com/changes/worldwide/0000000000?clientrequestid=b10c5ed1-bad1-445f-b386-b919946339a7).
4039
4140
As a customer, you can use this web service to:
4241
⋯ 11 unchanged lines
5453
5554
For more information, see:
5655
57
−- [Announcement blog post in the Office 365 Tech Community Forum](https://techcommunity.microsoft.com/t5/Office-365-Blog/Announcing-Office-365-endpoint-categories-and-Office-365-IP/ba-p/177638)
58
−- [Office 365 Tech Community Forum for questions about use of the web services](https://techcommunity.microsoft.com/t5/Office-365-Networking/bd-p/Office365Networking)
56
+- [Announcement blog post in the Tech Community Forum](https://techcommunity.microsoft.com/t5/Office-365-Blog/Announcing-Office-365-endpoint-categories-and-Office-365-IP/ba-p/177638)
57
+- [Tech Community Forum for questions about use of the web services](https://techcommunity.microsoft.com/t5/Office-365-Networking/bd-p/Office365Networking)
5958
6059
## Common parameters
6160
6261
These parameters are common across all the web service methods:
6362
6463
- **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.
65
−- **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.
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.
6665
6766
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/).
6867
⋯ 6 unchanged lines
7574
Parameters for the version web method are:
7675
7776
- **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.
78
−- **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.
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.
7978
- **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.
8079
8180
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:
8281
8382
- instance—The short name of the Microsoft 365 service instance.
8483
- latest—The latest version for endpoints of the specified instance.
85
−- versions—A list of all previous versions for the specified instance. This element is only included if the _AllVersions_ parameter is true.
84
+- versions—A list of all previous versions for the specified instance. This element is only included if the `AllVersions` parameter is true.
8685
8786
### Version web method examples
8887
⋯ 85 unchanged lines
174173
175174
Parameters for the endpoints web method are:
176175
177
−- **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.
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.
178177
- **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 (\*).
179
−- **NoIPv6=\<true \| false\>** —Set the value to _true_ to exclude IPv6 addresses from the output if you don't use IPv6 in your network.
180
−- **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_.
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`.
181180
182
−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.
181
+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.
183182
184183
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:
185184
186185
- id—The immutable ID number of the endpoint set.
187
−- serviceArea—The service area that this is part of: _Common_, _Exchange_, _SharePoint_, or _Skype_.
186
+- serviceArea—The service area that this is part of: `Common`, `Exchange`, `SharePoint`, or `Skype`.
188187
- urls—URLs for the endpoint set. A JSON array of DNS records. Omitted if blank.
189188
- 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.
190189
- udpPorts—UDP ports for the IP address ranges in this endpoint set. Omitted if blank.
191190
- 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.
192
−- 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.
193
−- expressRoute — _True_ if this endpoint set is routed over ExpressRoute, _False_ if not.
194
−- required — _True_ if this endpoint set is required to have connectivity for Microsoft 365 to be supported. _False_ if this endpoint set is optional.
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.
195194
- 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.
196195
197196
### Endpoints web method examples
⋯ 32 unchanged lines
230229
231230
The full output of the request in this example would contain other endpoint sets.
232231
233
−Example 2 request URI: [https://endpoints.office.com/endpoints/Worldwide?ServiceAreas=Exchange&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7](https://endpoints.office.com/endpoints/Worldwide?ServiceAreas=Exchange&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7)
232
+Example 2 request URI: [`https://endpoints.office.com/endpoints/Worldwide?ServiceAreas=Exchange&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7`](https://endpoints.office.com/endpoints/Worldwide?ServiceAreas=Exchange&ClientRequestId=b10c5ed1-bad1-445f-b386-b919946339a7)
234233
235234
This example obtains endpoints for the Microsoft 365 Worldwide instance for Exchange Online and dependencies only.
236235
⋯ 7 unchanged lines
244243
245244
The required parameter for the changes web method is:
246245
247
−- **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.
248247
249248
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.
250249
⋯ 1 unchanged line
252251
253252
- id—The immutable ID of the change record.
254253
- endpointSetId—The ID of the endpoint set record that is changed.
255
−- disposition—Describes what the change did to the endpoint set record. Values are _change_, _add_, or _remove_.
254
+- disposition—Describes what the change did to the endpoint set record. Values are `change`, `add`, or `remove`.
256255
- 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:
257256
- 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.
258257
- 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.
⋯ 4 unchanged lines
263262
- MovedIpOrUrl – We moved an IP address or Url between this endpoint set and another one. Generally no action is required.
264263
- RemovedDuplicateIpOrUrl – We removed a duplicate IP address or Url but it's still published for Microsoft 365. Generally no action is required.
265264
- OtherNonPriorityChanges – We changed something less critical than all of the other options, such as the contents of a note field.
266
−- 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.
267
−- 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_.
268
−- current—A substructure detailing updated values of changes elements on the endpoint set. Includes _ExpressRoute_, _serviceArea_, _category_, _required_, _tcpPorts_, _udpPorts_, and _notes_.
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`.
269268
- add —A substructure detailing items to be added to endpoint set collections. Omitted if there are no additions.
270269
— effectiveDate—Defines the data when the additions will be live in the service.
271
− — ips—Items to be added to the _ips_ array.
272
− — urls- Items to be added to the _urls_ array.
270
+ — ips—Items to be added to the `ips` array.
271
+ — urls- Items to be added to the `urls` array.
273272
- remove—A substructure detailing items to be removed from the endpoint set. Omitted if there are no removals.
274
− — ips—Items to be removed from the _ips_ array.
275
− — urls- Items to be removed from the _urls_ array.
273
+ — ips—Items to be removed from the `ips` array.
274
+ — urls- Items to be removed from the `urls` array.
276275
277276
### Changes web method examples
278277
⋯ 73 unchanged lines
352351
The script does the following:
353352
354353
- Checks the version number of the current Microsoft 365 Worldwide instance endpoints by calling the web service REST API.
355
−- Checks for a current version file at _$Env:TEMP\O365_endpoints_latestversion.txt_. The path of the global variable **$Env:TEMP** is usually _C:\Users\\<username\>\AppData\Local\Temp_.
356
−- If 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:
354
+- Checks for a current version file at `$Env:TEMP\O365_endpoints_latestversion.txt`. The path of the global variable **$Env:TEMP** is usually `C:\Users\\<username\>\AppData\Local\Temp`.
355
+- If 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:
357356
358357
``` powershell
359358
$versionpath = $Env:TEMP + "\O365_endpoints_latestversion.txt"
360359
$datapath = $Env:TEMP + "\O365_endpoints_data.txt"
361360
```
362361
363
−- 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.
364
−- 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.
362
+- 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.
363
+- 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.
365364
366
−The script generates a unique _ClientRequestId_ for the computer it's executed on, and reuses this ID across multiple calls. This ID is stored in the _O365_endpoints_latestversion.txt_ file.
365
+The script generates a unique `ClientRequestId` for the computer it's executed on, and reuses this ID across multiple calls. This ID is stored in the `O365_endpoints_latestversion.txt` file.
367366
368367
### To run the PowerShell script
369368
370
−1. Copy the script and save it to your local hard drive or script location as _Get-O365WebServiceUpdates.ps1_.
369
+1. Copy the script and save it to your local hard drive or script location as `Get-O365WebServiceUpdates.ps1`.
371370
1. 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:
372371
373372
``` powershell
⋯ 150 unchanged lines
524523
525524
## Example Python Script
526525
527
−Here's 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 Microsoft 365 Worldwide instance endpoints. When there's 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. Call this script once an hour to check for a version update.
526
+Here's 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 Microsoft 365 Worldwide instance endpoints. When there's 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. Call this script once an hour to check for a version update.
528527
529528
```python
530529
import json
⋯ 71 unchanged lines
602601
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.
603602
604603
- To use a Power Automate solution, see [Use Power Automate to receive an email for changes to Microsoft 365 IP Addresses and URLs](https://techcommunity.microsoft.com/t5/Office-365-Networking/Use-Microsoft-Flow-to-receive-an-email-for-changes-to-Office-365/m-p/240651).
605
−- To deploy an Azure Logic App using an ARM template, see [Office 365 Update Notification (v1.1)](https://aka.ms/ipurlws-updates-template).
606604
- To write your own notification script using PowerShell, see [Send-MailMessage](/powershell/module/microsoft.powershell.utility/send-mailmessage).
607605
608606
## Exporting a Proxy PAC file
609607
610608
[Get-PacFile](https://www.powershellgallery.com/packages/Get-PacFile) is a PowerShell script that reads the latest network endpoints from the Microsoft 365 IP Address and URL web service and creates a sample PAC file. For information on using Get-PacFile, see [Use a PAC file for direct routing of vital Microsoft 365 traffic](managing-office-365-endpoints.md#use-a-pac-file-for-direct-routing-of-vital-microsoft-365-traffic).
611609
612
−## Related articles
613
−
614
−[Microsoft 365 URLs and IP address ranges](https://support.office.com/article/8548a211-3fe7-47cb-abb1-355ea5aa88a2)
615
−
616
−[Managing Microsoft 365 endpoints](managing-office-365-endpoints.md)
617
−
618
−[Microsoft 365 Network Connectivity Principles](microsoft-365-network-connectivity-principles.md)
619
−
620
−[Microsoft 365 network and performance tuning](network-planning-and-performance.md)
621
−
622
−[Assessing Microsoft 365 network connectivity](assessing-network-connectivity.md)
623
−
624
−[Media Quality and Network Connectivity Performance in Skype for Business Online](https://support.office.com/article/5fe3e01b-34cf-44e0-b897-b0b2a83f0917)
625
−
626
−[Optimizing your network for Skype for Business Online](https://support.office.com/article/b363bdca-b00d-4150-96c3-ec7eab5a8a43)
627
−
628
−[Microsoft 365 performance tuning using baselines and performance history](performance-tuning-using-baselines-and-history.md)
610
+## Related content
629611
630
−[Performance troubleshooting plan for Microsoft 365](performance-troubleshooting-plan.md)
612
+- [Microsoft 365 URLs and IP address ranges](urls-and-ip-address-ranges.md)
613
+- [Managing Microsoft 365 endpoints](managing-office-365-endpoints.md)
614
+- [Microsoft 365 Network Connectivity Principles](microsoft-365-network-connectivity-principles.md)
615
+- [Microsoft 365 network and performance tuning](network-planning-and-performance.md)
616
+- [Assessing Microsoft 365 network connectivity](assessing-network-connectivity.md)
617
+- [Media Quality and Network Connectivity Performance in Skype for Business Online](https://support.office.com/article/5fe3e01b-34cf-44e0-b897-b0b2a83f0917)
618
+- [Optimizing your network for Skype for Business Online](https://support.office.com/article/b363bdca-b00d-4150-96c3-ec7eab5a8a43)
619
+- [Microsoft 365 performance tuning using baselines and performance history](performance-tuning-using-baselines-and-history.md)
620
+- [Performance troubleshooting plan for Microsoft 365](performance-troubleshooting-plan.md)
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.