Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add AssessPatches API #9275

Merged
merged 14 commits into from
Jun 8, 2020
Merged

Add AssessPatches API #9275

Show file tree
Hide file tree
Changes from 12 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
3e26f32
Initial commit with updates to compute.json for assessPatches and sof…
mirichmo Apr 24, 2020
202ea39
Add VirtualMachinesAssessPatches.json
mirichmo Apr 24, 2020
7709079
Fix minor issues with softwarePatches
mirichmo Apr 25, 2020
776233c
Updates to correct the example per oav
mirichmo Apr 28, 2020
2c67d51
Remove GET and LIST softwarePatches
mirichmo Apr 28, 2020
61099a3
Remove unneeded list result
mirichmo Apr 28, 2020
d922d8b
update description strings
mirichmo Apr 29, 2020
76dffd9
Add kbid to spell check list. Include Prettier formating changes.
mirichmo Apr 29, 2020
16c5cb2
Update SoftwarePatch.InstallationState to AssessmentState
mirichmo May 2, 2020
95e4332
Remove extra properties from patch object array
mirichmo May 7, 2020
250d6a0
Fix name of PublishedDate
mirichmo May 11, 2020
ccbe1d5
Add generic error response
mirichmo Jun 5, 2020
96042e4
Add readonly, make rebootPending a boolean again
mirichmo Jun 6, 2020
dba1bc1
Remove LastModifiedDateTime from result object
mirichmo Jun 6, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions custom-words.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -748,6 +748,7 @@ jumpbox
jwts
kafkarest
Kaliningrad
kbid
Kbps
KECA
kernelspec
Expand Down
204 changes: 204 additions & 0 deletions specification/compute/resource-manager/Microsoft.Compute/stable/2020-06-01/compute.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3490,6 +3490,63 @@
}
}
},
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachines/{vmName}/assessPatches": {
"post": {
"tags": [
"VirtualMachines"
],
"operationId": "VirtualMachines_AssessPatches",
"x-ms-examples": {
"Assess patch state of a virtual machine.": {
"$ref": "./examples/VirtualMachineAssessPatches.json"
}
},
"description": "Assess patches on the VM.",
"parameters": [
{
"name": "resourceGroupName",
"in": "path",
"required": true,
"type": "string",
"description": "The name of the resource group."
},
{
"name": "vmName",
"in": "path",
"required": true,
"type": "string",
"description": "The name of the virtual machine."
},
{
"$ref": "#/parameters/ApiVersionParameter"
},
{
"$ref": "#/parameters/SubscriptionIdParameter"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"$ref": "#/definitions/VirtualMachineAssessPatchesResult"
}
},
"202": {
"description": "Accepted"
mirichmo marked this conversation as resolved.
Show resolved Hide resolved
},
"default": {
"description": "Error response describing why the operation failed.",
"schema": {
"$ref": "#/definitions/CloudError"
}
}
},
"x-ms-long-running-operation": true,
"x-ms-long-running-operation-options": {
"final-state-via": "location"
}
}
},
"/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/virtualMachineScaleSets/{vmScaleSetName}": {
"put": {
"tags": [
Expand Down Expand Up @@ -7056,6 +7113,153 @@
},
"description": "The List Extension operation response"
},
"VirtualMachineSoftwarePatchProperties": {
"properties": {
"patchId": {
mirichmo marked this conversation as resolved.
Show resolved Hide resolved
"type": "string",
"description": "A unique identifier for the patch."
},
"name": {
"type": "string",
"description": "The friendly name of the patch."
},
"version": {
"type": "string",
"description": "The version number of the patch. This property applies only to Linux patches."
},
"kbid": {
"type": "string",
"description": "The KBID of the patch. Only applies to Windows patches."
},
"classifications": {
"type": "array",
"items": {
"type": "string"
},
"description": "The classification(s) of the patch as provided by the patch publisher."
},
"rebootBehavior": {
"type": "string",
"description": "Describes the reboot requirements of the patch.",
"enum": [
"NeverReboots",
"AlwaysRequiresReboot",
"CanRequestReboot"
],
"x-ms-enum": {
"name": "SoftwareUpdateRebootBehavior",
"modelAsString": true
mirichmo marked this conversation as resolved.
Show resolved Hide resolved
}
},
"activityId": {
"type": "string",
"description": "The activity ID of the operation that produced this result. It is used to correlate across CRP and extension logs."
},
"publishedDate": {
"type": "string",
"format": "date-time",
"description": "The UTC timestamp when the repository published this patch."
},
"lastModifiedDateTime": {
"type": "string",
"format": "date-time",
"description": "The UTC timestamp of the last update to this patch record."
},
"assessmentState": {
"type": "string",
"description": "Describes the outcome of an install operation for a given patch.",
"enum": [
"Installed",
"Failed",
"Excluded",
"NotSelected",
"Pending",
"Available"
],
"x-ms-enum": {
"name": "PatchAssessmentState",
"modelAsString": true
mirichmo marked this conversation as resolved.
Show resolved Hide resolved
}
}
},
"description": "Describes the properties of a Virtual Machine software patch."
},
"VirtualMachineAssessPatchesResult": {
"properties": {
"status": {
"type": "string",
"readOnly": true,
"description": "The overall success or failure status of the operation. It remains \"InProgress\" until the operation completes. At that point it will become \"Failed\", \"Succeeded\", or \"CompletedWithWarnings.\"",
"enum": [
"InProgress",
"Failed",
"Succeeded",
"CompletedWithWarnings"
],
"x-ms-enum": {
"name": "PatchOperationStatus",
"modelAsString": true
mirichmo marked this conversation as resolved.
Show resolved Hide resolved
}
},
"assessmentActivityId": {
"type": "string",
"readOnly": true,
"description": "The activity ID of the operation that produced this result. It is used to correlate across CRP and extension logs."
},
"rebootPending": {
"type": "string",
"readOnly": true,
"description": "The overall reboot status of the VM. It will be true when partially installed patches require a reboot to complete installation but the reboot has not yet occurred.",
"enum": [
"true",
"false"
mirichmo marked this conversation as resolved.
Show resolved Hide resolved
],
mirichmo marked this conversation as resolved.
Show resolved Hide resolved
"x-ms-enum": {
"name": "RebootPending",
"modelAsString": true
}
},
"criticalAndSecurityPatchCount": {
"type": "integer",
"readOnly": true,
"format": "int32",
"description": "The number of critical or security patches that have been detected as available and not yet installed."
},
"otherPatchCount": {
"type": "integer",
"readOnly": true,
"format": "int32",
"description": "The number of all available patches excluding critical and security."
},
"startDateTime": {
"type": "string",
"readOnly": true,
"format": "date-time",
"description": "The UTC timestamp when the operation began."
},
"lastModifiedDateTime": {
"type": "string",
"readOnly": true,
"format": "date-time",
"description": "The UTC timestamp of the last update of this result object."
},
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when does this and the "InProgress" state come into play? With the 202 + location header async pattern the user is not going to get a result until the operation is complete.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention with those two properties is consistency of results so that the data returned directly, the data acquired via GET InstanceView, and the data acquired via the upcoming installationResults API all align. LastModifiedDateTime and "status": "InProgress" make more sense in the context of InstanceView.

In terms of this specific API, "InProgress" is unlikely to ever be returned since it should not return results until the operation completes, but the underlying enum in the code contains the value so I thought I had to include it here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought about it some more and the lastModifiedDateTime doesn't really make sense since it is obviously the time when the response is returned. I removed it.

"patches": {
"type": "array",
"readOnly": true,
"items": {
"x-ms-client-flatten": true,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"x-ms-client-flatten": true, [](start = 12, length = 28)

does this have any effect? How does an array get flattened in SDKs?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found the documentation here. I think the answer to your question is, "yes." The results are included as I expected them to be in the SDK (A list of patch objects without additional "properties" objects or nesting inside them). I don't know if it would have been generated that way without the extension tag.

"$ref": "#/definitions/VirtualMachineSoftwarePatchProperties"
},
"description": "The list of patches that have been detected as available for installation."
},
"error": {
"$ref": "#/definitions/ApiError",
"readOnly": true,
"description": "The errors that were encountered during execution of the operation. The details array contains the list of them."
}
},
"description": "Describes the properties of an AssessPatches result."
},
"PurchasePlan": {
"properties": {
"publisher": {
Expand Down
53 changes: 53 additions & 0 deletions ...rce-manager/Microsoft.Compute/stable/2020-06-01/examples/VirtualMachineAssessPatches.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
{
"parameters": {
"subscriptionId": "{subscription-id}",
"resourceGroupName": "myResourceGroupName",
"vmName": "myVMName",
"api-version": "2020-06-01"
},
"responses": {
"200": {
"body": {
"status": "Succeeded",
"assessmentActivityId": "68f8b292-dfc2-4646-9781-33cc88631968",
"rebootPending": "true",
"criticalAndSecurityPatchCount": 1,
"otherPatchCount": 2,
"startDateTime": "2020-04-24T21:02:04.2556154Z",
"lastModifiedDateTime": "2020-04-24T21:18:45.2830263Z",
"patches": [
{
"patchId": "35428702-5784-4ba4-a6e0-5222258b5411",
"name": "Definition Update for Windows Defender Antivirus - KB2267602 (Definition 1.279.1373.0)",
"version": "",
"kbid": "2267602",
"classifications": [
"Definition Updates"
],
"rebootBehavior": "NeverReboots",
"activityId": "68f8b292-dfc2-4646-9781-33cc88631968",
"publishedDate": "2018-11-07T00:00:00Z",
"lastModifiedDateTime": "2020-04-24T21:18:45.2830263Z",
"assessmentState": "Available"
},
{
"patchId": "39f9cdd1-795c-4d0e-8c0a-73ab3f31746d",
"name": "Windows Malicious Software Removal Tool x64 - October 2018 (KB890830)",
"version": "",
"kbid": "890830",
"classifications": [
"Update Rollups"
],
"rebootBehavior": "CanRequestReboot",
"activityId": "68f8b292-dfc2-4646-9781-33cc88631968",
"publishedDate": "2018-11-07T00:00:00Z",
"lastModifiedDateTime": "2020-04-24T21:18:45.2830263Z",
"assessmentState": "Available"
}
],
"error": null
}
},
"202": {}
}
}