[Storage Queue] How to use retry policy?

[gmantri]

• Package Name: @azure/storage-queue
• Package Version: 12.1.0
• Operating system: macOS
• nodejs
  • version: 10.16.3
• browser
  • name/version:
• typescript
  • version:
• Is the bug related to documentation in
  • README.md
  • source code documentation
  • SDK API docs on https://docs.microsoft.com

Describe the bug
In the older versions of SDK, defining a retry policy was rather simple using something like the following:

const retryOperations = new azure.ExponentialRetryPolicyFilter(5);
return azure.createQueueService(connectionString).withFilter(retryOperations);

I am wondering how can we do the same with the new SDK. I looked around but could not find any information/code samples regarding that. Any pointers will be highly appreciated.

[ramya-rao-a]

Thanks for reporting @gmantri

@xirzec This falls into the bucket of some common documentation we should have in this repo that applies across packages to cover topics like retries and logging. Can you log an issue to track all such documentation we want to have?

@jeremymeng Meanwhile, can you share pointers on how to use the retry policy?

[gmantri]

Thanks @ramya-rao-a!

One more issue I would like to pile on with this is the ability to add client request id in the new SDK. I looked around but could not find a way to include that in the SDK. In the older SDK, it was as simple as clientRequestId as one of the request options. I would appreciate if documentation can be updated to include a sample for that as well.

On a different note, is there a way I can contribute towards improving the documentation? I have been using SDK quite extensively and there are places where documentation needs more details.

For example, take a look at the SignedIdentifier. The documentation simply states that accessPolicy should be an object however it fails to describe the structure of that object. When I used it, I found that the structure of this object should be something like the following:

{
  permissions: "<permission-string>",
  startsOn: Date/Time value or undefined,
  expiresOn: Date/Time value or undefined
}

I could possibly try and fix the documentation wherever it is possible.

[xirzec]

@ramya-rao-a the tracking issue for core documentation is here: #10239

@gmantri We automatically set a client request id in this policy: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/core/core-http/src/policies/generateClientRequestIdPolicy.ts

If you really want to set your own header for this you could set a custom header with the correct name: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/core/core-http/src/operationOptions.ts#L31

The SignedIdentifier doc issue looks like something is broken in the docs pipeline, since the definition here looks similar to what you discovered:

azure-sdk-for-js/sdk/storage/storage-queue/src/QueueClient.ts

Line 183 in 2f62dda

export interface SignedIdentifier {

[gmantri]

Thanks @xirzec for replying. I am wondering if you can share a code sample for setting custom header. I looked up the link you shared but unfortunately still clueless as to how you would go about using it. I would really appreciate that.

[jeremymeng]

@gmantri Storage libraries don't use OperationOptions from core-http. So customHeaders does not exist in their option types. However if you are using JavaScript, you can add it to the options object like below:

blobServiceClient.listContainers({
        customHeaders: {
          myheader: "my header value"
        }
      })

We also have a sample showing how to set the x-ms-client-request-id using a custom policy.

[jeremymeng]

For retry please use StorageRetryOptions to customize the pipeline:

azure-sdk-for-js/sdk/storage/storage-queue/samples/typescript/src/customPipeline.ts

Lines 26 to 28 in 5fa7f3f

	retryOptions: {
	maxTries: 4
	}, // Retry options

[jeremymeng]

@gmantri Please let us know if you have any further questions. We have tracked the doc issue of Object type in another system.

[gmantri]

@jeremymeng Thank you for your help! I am all set.