Merge pull request #1765 from grafana/aws/v0.13.0

Document jslib-aws v0.13.0 changes
grafana · Nov 11, 2024 · 92e8a24 · 92e8a24
2 parents 5f4e1e4 + 2f70d0e
commit 92e8a24
Show file tree

Hide file tree

Showing 10 changed files with 284 additions and 14 deletions.
diff --git a/docs/sources/k6/next/javascript-api/jslib/aws/KMSClient/listKeys.md b/docs/sources/k6/next/javascript-api/jslib/aws/KMSClient/listKeys.md
@@ -23,7 +23,10 @@ weight: 10
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.11.0/kms.js';
+import {
+  AWSConfig,
+  KMSClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/k6/next/javascript-api/jslib/aws/S3Client/Bucket.md b/docs/sources/k6/next/javascript-api/jslib/aws/S3Client/Bucket.md
@@ -19,7 +19,10 @@ Bucket is returned by the S3Client.\* methods that query S3 buckets. Namely, `li
 {{< code >}}
 
 ```javascript
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.12.1/s3.js';
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/k6/next/javascript-api/jslib/aws/S3Client/abortMultipartUpload.md b/docs/sources/k6/next/javascript-api/jslib/aws/S3Client/abortMultipartUpload.md
@@ -28,7 +28,10 @@ weight: 10
 {{< code >}}
 
 ```javascript
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.12.1/s3.js';
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/k6/next/javascript-api/jslib/aws/S3Client/getObject.md b/docs/sources/k6/next/javascript-api/jslib/aws/S3Client/getObject.md
@@ -9,12 +9,17 @@ weight: 10
 
 `S3Client.getObject` downloads an object from a bucket.
 
+As a default, the object's data will be treated as a string. In order to treat the object's data as binary content, and
+receive the data as an `ArrayBuffer`, you can pass [`additionalHeaders`](#parameters) to `getObject`, with the `Accept` header set to
+`application/octet-stream`.
+
 ### Parameters
 
-| Parameter  | Type   | Description                                  |
-| :--------- | :----- | :------------------------------------------- |
-| bucketName | string | Name of the bucket to fetch the object from. |
-| objectKey  | string | Name of the object to download.              |
+| Parameter         | Type   | Description                                  |
+| :---------------- | :----- | :------------------------------------------- |
+| bucketName        | string | Name of the bucket to fetch the object from. |
+| objectKey         | string | Name of the object to download.              |
+| additionalHeaders | Object | Additional headers to send with the request. |
 
 ### Returns
 
@@ -24,6 +29,8 @@ weight: 10
 
 ### Example
 
+#### Downloading a text file from AWS S3
+
 {{< code >}}
 
 ```javascript
@@ -61,3 +68,41 @@ export default async function () {
 _A k6 script that will download an object from a bucket_
 
 {{< /code >}}
+
+#### Downloading a binary file from AWS S3
+
+{{< code >}}
+
+```javascript
+import exec from 'k6/execution';
+
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
+
+const awsConfig = new AWSConfig({
+  region: __ENV.AWS_REGION,
+  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
+  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
+});
+
+const s3 = new S3Client(awsConfig);
+const testBucketName = 'test-jslib-aws';
+const testFileKey = 'quick.pdf';
+
+export default async function () {
+  // Download an object from S3, and require from the `getObject` operation
+  // to treat it as a binary content's file, and return an Object who's data
+  // parameter is an ArrayBuffer.
+  const s3Object = await s3.getObject(testBucketName, testFileKey, {
+    Accept: 'application/octet-stream',
+  });
+
+  console.log(`Successfully downloaded a binary file of size ${s3Object.data.byteLength} bytes`);
+}
+```
+
+_A k6 script that will download a binary object from a bucket_
+
+{{< /code >}}
diff --git a/docs/sources/k6/next/javascript-api/jslib/aws/SQSClient/sendMessageBatch.md b/docs/sources/k6/next/javascript-api/jslib/aws/SQSClient/sendMessageBatch.md
@@ -0,0 +1,81 @@
+---
+aliases:
+title: 'sendMessageBatch'
+description: 'SQSClient.sendMessageBatch Delivers up to ten messages to the specified queue.'
+weight: 10
+---
+
+# sendMessage
+
+`SQSClient.sendMessageBatch(queueUrl, entries)` delivers up to ten messages to the specified Amazon Simple Queue
+Service (SQS) queue.
+
+### Parameters
+
+| Name       | Type                                            | Description                                                                                          |
+| :--------- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
+| `queueUrl` | string                                          | The URL of the Amazon SQS queue to which a message is sent. Queue URLs and names are case-sensitive. |
+| `entries`  | [SendMessageBatchEntry](#sendmessagebatchentry) | A list of up to ten messages to send.                                                                |
+
+#### SendMessageBatchEntry
+
+| Name              | Type                                                                                                                   | Description                                                                         |
+| :---------------- | :--------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- |
+| `messageId`       | string                                                                                                                 | The identifier of the batch entry message.                                          |
+| `messageBody`     | string                                                                                                                 | The message to send. The minimum size is one character. The maximum size is 256 KB. |
+| `messageOptions?` | [SendMessageOptions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/sqs/sendmessageoption)>) (optional) | Options for the request.                                                            |
+
+### Returns
+
+| Type                                                     | Description                                                     |
+| :------------------------------------------------------- | :-------------------------------------------------------------- |
+| `Promise<[MessageBatchResponse](#messagebatchresponse)>` | A Promise that fulfills with a batch message creation response. |
+
+#### MessageBatchResponse
+
+| Name         | Type              | Description                                                                                                                                                                                                                   |
+| :----------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `successful` | object[]          | A list of succesful messages as objects containing an `id` string property holding the unique identifier for the message, and a `bodyMD5` string property holding the MD5 digest of the non-URL-encoded message body string.. |
+| `failed`     | SQSServiceError[] | A list of error responses.                                                                                                                                                                                                    |
+
+### Example
+
+{{< code >}}
+
+```javascript
+import exec from 'k6/execution';
+
+import {
+  AWSConfig,
+  SQSClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/sqs.js';
+
+const awsConfig = new AWSConfig({
+  region: __ENV.AWS_REGION,
+  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
+  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
+  sessionToken: __ENV.AWS_SESSION_TOKEN,
+});
+
+const sqs = new SQSClient(awsConfig);
+const testQueue = 'https://sqs.us-east-1.amazonaws.com/000000000/test-queue';
+
+export default async function () {
+  // If our test queue does not exist, abort the execution.
+  const queuesResponse = await sqs.listQueues();
+  if (queuesResponse.queueUrls.filter((q) => q === testQueue).length == 0) {
+    exec.test.abort();
+  }
+
+  // Prepare a bunch of batch messages to add to the queue
+  const messageBatch = [
+    { messageId: '0', messageBody: 'test0' },
+    { messageId: '1', messageBody: 'test1' },
+  ];
+
+  // Send the batch of messages to the queue
+  await sqs.sendMessageBatch(testQueue, messageBatch);
+}
+```
+
+{{< /code >}}
diff --git a/docs/sources/k6/v0.47.x/javascript-api/jslib/aws/KMSClient/listKeys.md b/docs/sources/k6/v0.47.x/javascript-api/jslib/aws/KMSClient/listKeys.md
@@ -23,7 +23,10 @@ weight: 10
 ```javascript
 import exec from 'k6/execution';
 
-import { AWSConfig, KMSClient } from 'https://jslib.k6.io/aws/0.11.0/kms.js';
+import {
+  AWSConfig,
+  KMSClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/kms.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/k6/v0.51.x/javascript-api/jslib/aws/S3Client/Bucket.md b/docs/sources/k6/v0.51.x/javascript-api/jslib/aws/S3Client/Bucket.md
@@ -19,7 +19,10 @@ Bucket is returned by the S3Client.\* methods that query S3 buckets. Namely, `li
 {{< code >}}
 
 ```javascript
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.12.1/s3.js';
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/k6/v0.51.x/javascript-api/jslib/aws/S3Client/abortMultipartUpload.md b/docs/sources/k6/v0.51.x/javascript-api/jslib/aws/S3Client/abortMultipartUpload.md
@@ -28,7 +28,10 @@ weight: 10
 {{< code >}}
 
 ```javascript
-import { AWSConfig, S3Client } from 'https://jslib.k6.io/aws/0.12.1/s3.js';
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
 
 const awsConfig = new AWSConfig({
   region: __ENV.AWS_REGION,

diff --git a/docs/sources/k6/v0.52.x/javascript-api/jslib/aws/S3Client/getObject.md b/docs/sources/k6/v0.52.x/javascript-api/jslib/aws/S3Client/getObject.md
@@ -9,12 +9,17 @@ weight: 10
 
 `S3Client.getObject` downloads an object from a bucket.
 
+As a default, the object's data will be treated as a string. In order to treat the object's data as binary content, and
+receive the data as an `ArrayBuffer`, you can pass [`additionalHeaders`](#parameters) to `getObject`, with the `Accept` header set to
+`application/octet-stream`.
+
 ### Parameters
 
-| Parameter  | Type   | Description                                  |
-| :--------- | :----- | :------------------------------------------- |
-| bucketName | string | Name of the bucket to fetch the object from. |
-| objectKey  | string | Name of the object to download.              |
+| Parameter         | Type   | Description                                  |
+| :---------------- | :----- | :------------------------------------------- |
+| bucketName        | string | Name of the bucket to fetch the object from. |
+| objectKey         | string | Name of the object to download.              |
+| additionalHeaders | Object | Additional headers to send with the request. |
 
 ### Returns
 
@@ -24,6 +29,8 @@ weight: 10
 
 ### Example
 
+#### Downloading a text file from AWS S3
+
 {{< code >}}
 
 ```javascript
@@ -61,3 +68,41 @@ export default async function () {
 _A k6 script that will download an object from a bucket_
 
 {{< /code >}}
+
+#### Downloading a binary file from AWS S3
+
+{{< code >}}
+
+```javascript
+import exec from 'k6/execution';
+
+import {
+  AWSConfig,
+  S3Client,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/s3.js';
+
+const awsConfig = new AWSConfig({
+  region: __ENV.AWS_REGION,
+  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
+  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
+});
+
+const s3 = new S3Client(awsConfig);
+const testBucketName = 'test-jslib-aws';
+const testFileKey = 'quick.pdf';
+
+export default async function () {
+  // Download an object from S3, and require from the `getObject` operation
+  // to treat it as a binary content's file, and return an Object who's data
+  // parameter is an ArrayBuffer.
+  const s3Object = await s3.getObject(testBucketName, testFileKey, {
+    Accept: 'application/octet-stream',
+  });
+
+  console.log(`Successfully downloaded a binary file of size ${s3Object.data.byteLength} bytes`);
+}
+```
+
+_A k6 script that will download a binary object from a bucket_
+
+{{< /code >}}
diff --git a/docs/sources/k6/v0.53.x/javascript-api/jslib/aws/SQSClient/sendMessageBatch.md b/docs/sources/k6/v0.53.x/javascript-api/jslib/aws/SQSClient/sendMessageBatch.md
@@ -0,0 +1,81 @@
+---
+aliases:
+title: 'sendMessageBatch'
+description: 'SQSClient.sendMessageBatch Delivers up to ten messages to the specified queue.'
+weight: 10
+---
+
+# sendMessage
+
+`SQSClient.sendMessageBatch(queueUrl, entries)` delivers up to ten messages to the specified Amazon Simple Queue
+Service (SQS) queue.
+
+### Parameters
+
+| Name       | Type                                            | Description                                                                                          |
+| :--------- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
+| `queueUrl` | string                                          | The URL of the Amazon SQS queue to which a message is sent. Queue URLs and names are case-sensitive. |
+| `entries`  | [SendMessageBatchEntry](#sendmessagebatchentry) | A list of up to ten messages to send.                                                                |
+
+#### SendMessageBatchEntry
+
+| Name              | Type                                                                                                                   | Description                                                                         |
+| :---------------- | :--------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- |
+| `messageId`       | string                                                                                                                 | The identifier of the batch entry message.                                          |
+| `messageBody`     | string                                                                                                                 | The message to send. The minimum size is one character. The maximum size is 256 KB. |
+| `messageOptions?` | [SendMessageOptions](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/jslib/sqs/sendmessageoption)>) (optional) | Options for the request.                                                            |
+
+### Returns
+
+| Type                                                     | Description                                                     |
+| :------------------------------------------------------- | :-------------------------------------------------------------- |
+| `Promise<[MessageBatchResponse](#messagebatchresponse)>` | A Promise that fulfills with a batch message creation response. |
+
+#### MessageBatchResponse
+
+| Name         | Type              | Description                                                                                                                                                                                                                   |
+| :----------- | :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `successful` | object[]          | A list of succesful messages as objects containing an `id` string property holding the unique identifier for the message, and a `bodyMD5` string property holding the MD5 digest of the non-URL-encoded message body string.. |
+| `failed`     | SQSServiceError[] | A list of error responses.                                                                                                                                                                                                    |
+
+### Example
+
+{{< code >}}
+
+```javascript
+import exec from 'k6/execution';
+
+import {
+  AWSConfig,
+  SQSClient,
+} from 'https://jslib.k6.io/aws/{{< param "JSLIB_AWS_VERSION" >}}/sqs.js';
+
+const awsConfig = new AWSConfig({
+  region: __ENV.AWS_REGION,
+  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
+  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
+  sessionToken: __ENV.AWS_SESSION_TOKEN,
+});
+
+const sqs = new SQSClient(awsConfig);
+const testQueue = 'https://sqs.us-east-1.amazonaws.com/000000000/test-queue';
+
+export default async function () {
+  // If our test queue does not exist, abort the execution.
+  const queuesResponse = await sqs.listQueues();
+  if (queuesResponse.queueUrls.filter((q) => q === testQueue).length == 0) {
+    exec.test.abort();
+  }
+
+  // Prepare a bunch of batch messages to add to the queue
+  const messageBatch = [
+    { messageId: '0', messageBody: 'test0' },
+    { messageId: '1', messageBody: 'test1' },
+  ];
+
+  // Send the batch of messages to the queue
+  await sqs.sendMessageBatch(testQueue, messageBatch);
+}
+```
+
+{{< /code >}}