Enhancements to docs for consistent examples of both PowerShell and bash#133
Enhancements to docs for consistent examples of both PowerShell and bash#133peterbom wants to merge 6 commits into
Conversation
| You should now have the following variables defined: | ||
| - `AZ_BATCH_SOFTWARE_ENTITLEMENT_TOKEN` | ||
| - `AZ_BATCH_ACCOUNT_URL` | ||
| - `applicationId` |
There was a problem hiding this comment.
Do we need to call out that the first two are environment variables and the last one is a shell variable?
| "expiry": "2019-01-16T01:06:07+00:00" | ||
| } | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Might be worth adding a snippet to quantify the similarity/difference.
Perhaps
The actual
idvalue andexpirytimestamp will differ, but the structure will be the same.
??
There was a problem hiding this comment.
Added descriptive comments to the fields themselves.
| $AZ_BATCH_ACCOUNT_URL/softwareEntitlements?api-version=$apiVersion \ | ||
| $AZ_BATCH_ACCOUNT_URL/softwareEntitlements?api-version=9999-09-09.99.99 \ | ||
| | jq -re '.entitlementId' || (echo "FAILED: entitlementId not found in JSON response" 1>&2)) | ||
| ``` |
There was a problem hiding this comment.
Need to precede these with examples showing the actual response from the server before showing the slice/dice of these as they extract the entitlementId.
There was a problem hiding this comment.
Agree it'd be informative and consistent to include the server response. I wasn't certain how to do so while:
- Only documenting the bulk of the request (
Invoke-RestMethodorcurl) once, to reduce clutter and ease maintenance - Providing a minimal set of commands (as few as possible) for the user to cut and paste (i.e. I'd prefer to avoid two separate commands for storing the server response and parsing out the entitlement id)
How about this approach? I've kept the commands unchanged, but added a description of what the response content looks like (before the entitlementId is extracted out).
| @@ -287,79 +342,38 @@ $ curl \ | |||
| --silent \ | |||
| --header "Content-Type: application/json; odata=minimalmetadata" \ | |||
| --data "{'duration':'PT5M'}" \ | |||
There was a problem hiding this comment.
Include a link to the REST API documentation?
There was a problem hiding this comment.
Where's the (public) REST API documentation?
|
This has come together really well. |
…might differ from the examples
| ```json | ||
| { | ||
| "id": "entitlement-695c822b-470c-4fd1-b34d-9b21435f57b2", // every entitlement has a unique identifier | ||
| "expiry": "2019-01-16T01:06:07+00:00" // reflects the expiry of the token, so all requests passing the same token will have the same expiry |
There was a problem hiding this comment.
We should probably remove this in a subsequent PR. Returning the expiry value is part of the pre-leasing "V2" API which was never deployed in production.
2 participants
Most of the walk-through (and related documents, build-guide and finding-certificates) give example commands only in PowerShell.
I added some bash examples when doing the work on the leasing API, but there was no obvious way to go through the entire walk-through (particularly building
sestest, running the test server, and generating certificates) without using some PowerShell, making the bash examples somewhat redundant.This adds a bash "wrapper" for
sestest, equivalent tosestest.ps1, making it easier to run the test server and generate certificates in bash, and uses this throughout the walk-through.I've also experimented with swapping the "generating a token" and "starting the test server" sections to reduce the required number of switches between shell windows, and keep the "client-side" commands (generating and verifying tokens) all in one place. I find this makes the document easier to read, but it's done as separate commits so it's easy to back out if preferred.