Merge pull request #224567 from diberry/diberry/0120-storage-queue-encoding

JS - queue - s365, public issue 78550

Author: v-shils

articles/storage/queues/storage-nodejs-how-to-use-queues.md

@@ -5,7 +5,7 @@ description: Learn to use the Azure Queue Storage to create and delete queues. L
 author: normesta
 ms.author: normesta
 ms.reviewer: dineshm
-ms.date: 12/21/2020
+ms.date: 01/20/2023
 ms.topic: how-to
 ms.service: storage
 ms.subservice: queues
@@ -39,150 +39,70 @@ The [Azure Storage client library for JavaScript](https://github.com/Azure/azure
 
 1. Use a command-line interface such as PowerShell (Windows), Terminal (Mac), or Bash (Unix), navigate to the folder where you created your sample application.
 
-# [JavaScript v12 SDK](#tab/javascript)
-
 1. Type `npm install @azure/storage-queue` in the command window.
 
 1. Verify that a `node_modules` folder was created. Inside that folder you'll find the `@azure/storage-queue` package, which contains the client library you need to access storage.
 
-# [JavaScript v2](#tab/javascript2)
-
-1. Type `npm install azure-storage` in the command window.
-
-1. Verify that a `node_modules` folder was created. Inside that folder, you'll find the `azure-storage` package, which contains the libraries you need to access storage.
-
----
-
 ### Import the package
 
 Using your code editor, add the following to the top the JavaScript file where you intend to use queues.
 
-# [JavaScript v12 SDK](#tab/javascript)
-
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_ImportStatements":::
 
-# [JavaScript v2](#tab/javascript2)
-
-```javascript
-var azure = require('azure-storage');
-```
-
----
 
 ## How to create a queue
 
-# [JavaScript v12 SDK](#tab/javascript)
 
 The following code gets the value of an environment variable called `AZURE_STORAGE_CONNECTION_STRING` and uses it to create a [`QueueServiceClient`](/javascript/api/@azure/storage-queue/queueserviceclient) object. This object is then used to create a [`QueueClient`](/javascript/api/@azure/storage-queue/queueclient) object that allows you to work with a specific queue.
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_CreateQueue":::
 
 If the queue already exists, an exception is thrown.
 
-# [JavaScript v2](#tab/javascript2)
+## How to format the message
 
-The Azure module will read the environment variables `AZURE_STORAGE_ACCOUNT` and `AZURE_STORAGE_ACCESS_KEY`, or `AZURE_STORAGE_CONNECTION_STRING` for information required to connect to your Azure Storage account. If these environment variables aren't set, you must specify the account information when calling `createQueueService`.
+The message type is a string. All messages are treated as strings. If you need to send a different data type, you need to serialize that datatype into a string when sending the message and deserialize the string format when reading the message.
 
-The following code creates a `QueueService` object, which enables you to work with queues.
+To convert **JSON** to a string format and back again in Node.js, use the following helper functions:
 
 ```javascript
-var queueSvc = azure.createQueueService();
-```
-
-Call the `createQueueIfNotExists` method to create a new queue with the specified name or return the queue if it already exists.
-
-```javascript
-queueSvc.createQueueIfNotExists('myqueue', function(error, results, response){
-  if(!error){
-    // Queue created or exists
-  }
-});
-```
-
-If the queue is created, `result.created` is true. If the queue exists, `result.created` is false.
-
----
+function jsonToBase64(jsonObj) {
+    const jsonString = JSON.stringify(jsonObj)
+    return  Buffer.from(jsonString).toString('base64')
+}
+function encodeBase64ToJson(base64String) {
+    const jsonString = Buffer.from(base64String,'base64').toString()
+    return JSON.parse(jsonString)
+}
+``` 
 
 ## How to insert a message into a queue
 
-# [JavaScript v12 SDK](#tab/javascript)
 
 To add a message to a queue, call the [`sendMessage`](/javascript/api/@azure/storage-queue/queueclient#sendmessage-string--queuesendmessageoptions-) method.
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_AddMessage":::
 
-# [JavaScript v2](#tab/javascript2)
-
-To insert a message into a queue, call the `createMessage` method to create a new message and add it to the queue.
-
-```javascript
-queueSvc.createMessage('myqueue', "Hello, World", function(error, results, response){
-  if(!error){
-    // Message inserted
-  }
-});
-```
-
----
 
 ## How to peek at the next message
 
 You can peek at messages in the queue without removing them from the queue by calling the `peekMessages` method.
 
-# [JavaScript v12 SDK](#tab/javascript)
 
 By default, [`peekMessages`](/javascript/api/@azure/storage-queue/queueclient#peekmessages-queuepeekmessagesoptions-) peeks at a single message. The following example peeks at the first five messages in the queue. If fewer than five messages are visible, just the visible messages are returned.
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_PeekMessage":::
 
-# [JavaScript v2](#tab/javascript2)
-
-By default, `peekMessages` peeks at a single message.
-
-```javascript
-queueSvc.peekMessages('myqueue', function(error, results, response){
-  if(!error){
-    // Message text is in results[0].messageText
-  }
-});
-```
-
-The `result` contains the message.
-
----
-
 Calling `peekMessages` when there are no messages in the queue won't return an error. However, no messages are returned.
 
 ## How to change the contents of a queued message
 
 The following example updates the text of a message.
 
-# [JavaScript v12 SDK](#tab/javascript)
-
 Change the contents of a message in-place in the queue by calling [`updateMessage`](/javascript/api/@azure/storage-queue/queueclient#updatemessage-string--string--string--number--queueupdatemessageoptions-).
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_UpdateMessage":::
 
-# [JavaScript v2](#tab/javascript2)
-
-Change the contents of a message in-place in the queue by calling `updateMessage`.
-
-```javascript
-queueSvc.getMessages('myqueue', function(error, getResults, getResponse){
-  if(!error){
-    // Got the message
-    var message = getResults[0];
-    queueSvc.updateMessage('myqueue', message.messageId, message.popReceipt, 10, {messageText: 'new text'}, function(error, updateResults, updateResponse){
-      if(!error){
-        // Message updated successfully
-      }
-    });
-  }
-});
-```
-
----
-
 ## How to dequeue a message
 
 Dequeueing a message is a two-stage process:
@@ -193,8 +113,6 @@ Dequeueing a message is a two-stage process:
 
 The following example gets a message, then deletes it.
 
-# [JavaScript v12 SDK](#tab/javascript)
-
 To get a message, call the [`receiveMessages`](/javascript/api/@azure/storage-queue/queueclient#receivemessages-queuereceivemessageoptions-) method. This call makes the messages invisible in the queue, so no other clients can process them. Once your application has processed a message, call [`deleteMessage`](/javascript/api/@azure/storage-queue/queueclient#deletemessage-string--string--queuedeletemessageoptions-) to delete it from the queue.
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_DequeueMessage":::
@@ -203,34 +121,8 @@ By default, a message is only hidden for 30 seconds. After 30 seconds it's visib
 
 Calling `receiveMessages` when there are no messages in the queue won't return an error. However, no messages will be returned.
 
-# [JavaScript v2](#tab/javascript2)
-
-To get a message, call the `getMessages` method. This call makes the messages invisible in the queue, so no other clients can process them. Once your application has processed a message, call `deleteMessage` to delete it from the queue.
-
-```javascript
-queueSvc.getMessages('myqueue', function(error, results, response){
-  if(!error){
-    // Message text is in results[0].messageText
-    var message = results[0];
-    queueSvc.deleteMessage('myqueue', message.messageId, message.popReceipt, function(error, response){
-      if(!error){
-        //message deleted
-      }
-    });
-  }
-});
-```
-
-By default, a message is only hidden for 30 seconds. After 30 seconds it's visible to other clients. You can specify a different value by using `options.visibilityTimeout` with `getMessages`.
-
-Using `getMessages` when there are no messages in the queue won't return an error. However, no messages will be returned.
-
----
-
 ## Additional options for dequeuing messages
 
-# [JavaScript v12 SDK](#tab/javascript)
-
 There are two ways you can customize message retrieval from a queue:
 
 - [`options.numberOfMessages`](/javascript/api/@azure/storage-queue/queuereceivemessageoptions#numberofmessages): Retrieve a batch of messages (up to 32).
@@ -240,106 +132,27 @@ The following example uses the `receiveMessages` method to get five messages in
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_DequeueMessages":::
 
-# [JavaScript v2](#tab/javascript2)
-
-There are two ways you can customize message retrieval from a queue:
-
-- `options.numOfMessages`: Retrieve a batch of messages (up to 32).
-- `options.visibilityTimeout`: Set a longer or shorter invisibility timeout.
-
-The following example uses the `getMessages` method to get 15 messages in one call. Then it processes each message using a `for` loop. It also sets the invisibility timeout to five minutes for all messages returned by this method.
-
-```javascript
-queueSvc.getMessages('myqueue', {numOfMessages: 15, visibilityTimeout: 5 * 60}, function(error, results, getResponse){
-  if(!error){
-    // Messages retrieved
-    for(var index in results){
-      // text is available in result[index].messageText
-      var message = results[index];
-      queueSvc.deleteMessage(queueName, message.messageId, message.popReceipt, function(error, deleteResponse){
-        if(!error){
-          // Message deleted
-        }
-      });
-    }
-  }
-});
-```
-
----
-
 ## How to get the queue length
 
-# [JavaScript v12 SDK](#tab/javascript)
 
 The [`getProperties`](/javascript/api/@azure/storage-queue/queueclient#getproperties-queuegetpropertiesoptions-) method returns metadata about the queue, including the approximate number of messages waiting in the queue.
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_QueueLength":::
 
-# [JavaScript v2](#tab/javascript2)
-
-The `getQueueMetadata` method returns metadata about the queue, including the approximate number of messages waiting in the queue.
-
-```javascript
-queueSvc.getQueueMetadata('myqueue', function(error, results, response){
-  if(!error){
-    // Queue length is available in results.approximateMessageCount
-  }
-});
-```
-
----
-
 ## How to list queues
 
-# [JavaScript v12 SDK](#tab/javascript)
-
 To retrieve a list of queues, call [`QueueServiceClient.listQueues`](/javascript/api/@azure/storage-queue/servicelistqueuesoptions#prefix). To retrieve a list filtered by a specific prefix, set [options.prefix](/javascript/api/@azure/storage-queue/servicelistqueuesoptions#prefix) in your call to `listQueues`.
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_ListQueues":::
 
-# [JavaScript v2](#tab/javascript2)
-
-To retrieve a list of queues, use `listQueuesSegmented`. To retrieve a list filtered by a specific prefix, use `listQueuesSegmentedWithPrefix`.
-
-```javascript
-queueSvc.listQueuesSegmented(null, function(error, results, response){
-  if(!error){
-    // results.entries contains the list of queues
-  }
-});
-```
-
-If all queues can't be returned, pass `result.continuationToken` as the first parameter of `listQueuesSegmented` or the second parameter of `listQueuesSegmentedWithPrefix` to retrieve more results.
-
----
-
 ## How to delete a queue
 
-# [JavaScript v12 SDK](#tab/javascript)
-
 To delete a queue and all the messages contained in it, call the [`DeleteQueue`](/javascript/api/@azure/storage-queue/queueclient#delete-queuedeleteoptions-) method on the `QueueClient` object.
 
 :::code language="javascript" source="~/azure-storage-snippets/queues/howto/JavaScript/JavaScript-v12/javascript-queues-v12.js" id="Snippet_DeleteQueue":::
 
 To clear all messages from a queue without deleting it, call [`ClearMessages`](/javascript/api/@azure/storage-queue/queueclient#clearmessages-queueclearmessagesoptions-).
 
-# [JavaScript v2](#tab/javascript2)
-
-To delete a queue and all the messages contained in it, call the `deleteQueue` method on the queue object.
-
-```javascript
-queueSvc.deleteQueue(queueName, function(error, response){
-  if(!error){
-    // Queue has been deleted
-  }
-});
-```
-
-To clear all messages from a queue without deleting it, call `clearMessages`.
-
----
-
 [!INCLUDE [storage-check-out-samples-all](../../../includes/storage-check-out-samples-all.md)]
 
 ## Next steps