MSUpdateAPI is a REST API designed to allow easy programmatic access to Windows Update Services without either:
- Running an entire on-prem WSUS implementation for the UpdateServices Powershell module to function
- Parsing HTML from the Microsoft Update Catalog and all of the pitfalls inherent with that approach
This is accomplished by directly connecting to the Windows Update Services SOAP endpoints, downloading the needed metadata, parsing, and storing it in a database for quick access with minimal storage requirements.
The application consists of three main components which are designed to run directly in Azure. These are:
- The database - A Cosmos DB NOSQL database for storing the metadata.
- UpdateProcessor - An Azure Function which handles reading, parsing, and inserting update metadata into the database.
- UpdateAPI - A REST API to provide access to the parsed metadata generated by the UpdateProcessor Azure Function. The API is containerized so that it can be used with Azure Container Apps
All of the above items are designed to comfortably reside within the limitations of the free grants provided by Azure.
The implementation of the WSUSSS protocol is taken from the update-server-server-sync repository, but has been heavily modified to add additional needed features and to add async functionality.
Both the API and the metadata processor require access to a Cosmos DB account for storing the parsed metadata. This is configured with the following environment variables:
DatabaseConfiguration__Uri = <the URI of your Cosmos DB endpoint>
DatabaseConfiguration__PrimaryKey = <Cosmos DB access key>
DatabaseConfiguration__DatabaseName = <the name of the database to be used in Cosmos DB>
Note that the API component only requires read access to the database, so a read only key should be used. Additionally, the metadata processor will automatically create the database with a manual throughput limit of 1000RU/s at the database level. As such you should not attempt to create the database yourself inside of Cosmos DB.
If running locally, you can use the Cosmos DB emulator and place the above configuration details in the appsettings.json and local.settings.json files for the API and metadata processor respectively.
Windows Update Services contain an enormous amount of updates, many of which are not likely to be needed for your particular use case. By limiting the types of updates and the products for which they apply, the time and storage needed for metadata download can be significantly reduced.
The metadata processor requries at least one update classification and one product to be defined. This is configured with the following environment variables:
Configuration__EnabledCategories__[0] = <the GUID of an update category>
Configuration__EnabledProducts__[0] = <the GUID of a product category>
Configuration__EnabledProducts__[1] = <the GUID of a product category>
Additional categories and products can be specified by adding additional environment variables and incrementing the value in the array index accessor (e.g. '[0]', '[1]', '[2]', etc). However, it is not recommended to enable a large number of products and categories, as amount of metadata to be processed can easily grow to unwieldy amounts.
Note that until an initial metadata sync has completed, all API endpoints except for Status at /api will return 503 Service Unavailable.
Easily check the state of the application
GET /api
{
"initialSyncComplete": true,
"state": "Loading Metadata"
}Lists the update categories enabled, or optionally all categories in the database
GET /api/category
[
{
"id": "0fa1201d-4330-4fa8-8ae9-b877473b6441",
"name": "Security Updates"
}
]| Name | Type | Purpose |
|---|---|---|
| ShowDisabled | bool | Request will return all categories in the database, instead of just those that are enabled |
GET /api/category?ShowDisabled=true
Lists the products enabled, or optionally all products in the database. Note that products are represented in a tree like structure with the root node always being Microsoft. The root node contains groupings for entire product lines, e.g. Windows.
GET /api/product
{
"id": "56309036-4c77-4dd9-951a-99ee9c246a94",
"name": "Microsoft",
"subproducts": [
{
"id": "6964aab4-c5b5-43bd-a17d-ffb4346a8e1d",
"name": "Windows",
"subproducts": [
{
"id": "72e7624a-5b00-45d2-b92f-e561c0a6a160",
"name": "Windows 11",
"subproducts": []
},
{
"id": "2c7888b6-f9e9-4ee9-87af-a77705193893",
"name": "Microsoft Server Operating System-22H2",
"subproducts": []
},
{
"id": "b3c75dc1-155f-4be4-b015-3f1a91758e52",
"name": "Windows 10, version 1903 and later",
"subproducts": []
},
{
"id": "f702a48c-919b-45d6-9aef-ca4248d50397",
"name": "Windows Server 2019",
"subproducts": []
}
]
}
]
}| Name | Type | Purpose |
|---|---|---|
| ShowDisabled | bool | Request will return all products in the database, instead of just those that are enabled |
GET /api/product?ShowDisabled=true
Lists the updates that match the enabled categories and products.
GET /api/update
[
{
"id": "36a4b6e1-3c98-4d7a-85d6-b92e434a6990",
"title": "2023-08 Cumulative Update for Microsoft server operating system, version 22H2 for x64-based Systems (KB5029250)",
"description": "Install this update to resolve issues in Windows. For a complete listing of the issues that are included in this update, see the associated Microsoft Knowledge Base article for more information. After you install this item, you may have to restart your computer.",
"creationDate": "2023-08-08T13:00:08-04:00",
"kbArticleId": "5029250",
"products": [
{
"id": "2c7888b6-f9e9-4ee9-87af-a77705193893",
"name": "Microsoft Server Operating System-22H2"
}
],
"classification": {
"id": "0fa1201d-4330-4fa8-8ae9-b877473b6441",
"name": "Security Updates"
},
"files": [
{
"fileName": "Windows10.0-KB5029250-x64.cab",
"source": "http://download.windowsupdate.com/d/msdownload/update/software/secu/2023/08/windows10.0-kb5029250-x64_bf3df74805686dd84faf8983aa55de2a5074bae3.cab",
"modifiedDate": "2023-08-04T12:00:58-04:00",
"digest": {
"algorithm": "SHA1",
"value": "BF3DF74805686DD84FAF8983AA55DE2A5074BAE3"
},
"size": 344979156
}
]
}
]| Name | Type | Purpose |
|---|---|---|
| Category | GUID | Filters updates to those matching the provided category GUID |
| Product | GUID | Filters updates to those matching the provided product GUID |
| Query | string | Filters updates to those containing the provided string in the title (case insensitive) |
GET /api/update?Category=0fa1201d-4330-4fa8-8ae9-b877473b6441&Product=2c7888b6-f9e9-4ee9-87af-a77705193893&Query=x64