Skip to content

Commit fe1cf9f

Browse files
oleiadeoleiade
committed
Add documentation for SQSClient
1 parent a7e90d5 commit fe1cf9f

File tree

4 files changed

+172
-3
lines changed

4 files changed

+172
-3
lines changed

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,25 +4,26 @@ excerpt: "aws is a library implementing APIs for accessing a selection of AWS se
44
description: "aws is a library implementing APIs for accessing a selection of AWS servicese"
55
---
66

7-
The `aws` module is a JavaScript library that wraps around some Amazon AWS services API.
7+
The `aws` module is a JavaScript library that wraps around some Amazon AWS services API.
88

99
The library exposes a couple of configuration and client classes allowing to interact with a subset of AWS services in the context of k6 load test scripts:
1010
- [S3Client](/javascript-api/jslib/aws/s3client): a class to list S3 buckets and the objects they contain, as well as uploading, downloading and deleting objects from them.
1111
- [SecretsManagerClient](/javascript-api/jslib/aws/secretsmanagerclient): a class to list, get, create, update, and delete secrets from the AWS secrets manager service.
1212
- [KMSClient](/javascript-api/jslib/aws/kmsclient): a class to list and generate keys from the AWS Key Management Service.
1313
- [SystemsManagerClient](/javascript-api/jslib/aws/systemsmanagerclient): a class to fetch parameters from the AWS Systems Manager Service.
14+
- [SQSClient](/javascript-api/jslib/aws/sqsclient): a class to list and send messages to SQS queues.
1415
- [SignatureV4](/javascript-api/jslib/aws/signaturev4): a class to sign and pre-sign requests to AWS services using the [Signature V4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) algorithm.
1516
- [AWSConfig](/javascript-api/jslib/aws/awsconfig/): a class is used by each client classes to provide them access to AWS credentials as well as configuration.
1617

17-
> ⭐️ Source code available on [GitHub](https://github.com/grafana/k6-jslib-aws).
18+
> ⭐️ Source code available on [GitHub](https://github.com/grafana/k6-jslib-aws).
1819
> Please request features and report bugs through [GitHub issues](https://github.com/grafana/k6-jslib-aws/issues).
1920
2021

2122
<Blockquote mod='info'>
2223

2324
#### This library is in active development
2425

25-
This library is stable enough to be useful, but pay attention to the new versions released on [jslib.k6.io](https://jslib.k6.io) and [k6-jslib-aws/releases](https://github.com/grafana/k6-jslib-aws/releases).
26+
This library is stable enough to be useful, but pay attention to the new versions released on [jslib.k6.io](https://jslib.k6.io) and [k6-jslib-aws/releases](https://github.com/grafana/k6-jslib-aws/releases).
2627

2728
This documentation is for the last version only. If you discover that some code below does not work, it most likely means that you are using an older version.
2829

@@ -35,5 +36,6 @@ This documentation is for the last version only. If you discover that some code
3536
| [S3Client](/javascript-api/jslib/aws/s3client) | Client class to interact with AWS S3 buckets and objects. |
3637
| [SecretsManager](/javascript-api/jslib/aws/secretsmanagerclient) | Client class to interact with AWS secrets stored in Secrets Manager. |
3738
| [KMSClient](/javascript-api/jslib/aws/kmsclient) | Client class to interact with AWS Key Management Service. |
39+
| [SQSClient](/javascript-api/jslib/aws/sqsclient) | Client class to interact with AWS Simple Queue Service. |
3840
| [SystemsManagerClient](/javascript-api/jslib/aws/systemsmanagerclient) | Client class to interact with AWS Systems Manager Service. |
3941
| [AWSConfig](/javascript-api/jslib/aws/awsconfig) | Class to configure AWS client classes. |

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/07 SQSClient.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: 'SQSClient'
3+
head_title: 'SQSClient'
4+
description: 'SQSClient enables interaction with the AWS Simple Queue Service (SQS)'
5+
excerpt: 'SQSClient allows interacting with the AWS Simple Queue Service (SQS)'
6+
---
7+
8+
`SQSClient` interacts with the AWS Simple Queue Service (SQS). With it, the user can send messages to specified queues and list available queues in the current region. `SQSClient` operations are blocking. k6 recommends reserving their use for the [`setup`](/using-k6/test-lifecycle/) and [`teardown`](/using-k6/test-lifecycle/) stages as much as possible.
9+
10+
Both the dedicated `sqs.js` jslib bundle and the all-encompassing `aws.js` bundle include the `SQSClient`.
11+
12+
### Methods
13+
14+
| Function | Description |
15+
| :--------------------------------------------------------------- | :--------------------------------------------------- |
16+
| [`sendMessage`](/javascript-api/jslib/aws/sqsclient/sqsclient-sendmessage) | Delivers a message to the specified queue. |
17+
| [`listQueues`](/javascript-api/jslib/aws/sqsclient/sqsclient-listqueues) | Returns a list of your queues in the current region. |
18+
19+
### Throws
20+
21+
`SQSClient` methods throw errors in case of failure.
22+
23+
| Error | Condition |
24+
| :---------------------- | :-------------------------------------------------------- |
25+
| `InvalidSignatureError` | when using invalid credentials |
26+
| `SQSServiceError` | when AWS replied to the requested operation with an error |
27+
28+
### Example
29+
30+
<CodeGroup labels={[]}>
31+
32+
```javascript
33+
import exec from 'k6/execution'
34+
35+
import { AWSConfig, SQSClient } from 'https://jslib.k6.io/aws/0.7.2/sqs.js'
36+
37+
const awsConfig = new AWSConfig({
38+
region: __ENV.AWS_REGION,
39+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
40+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
41+
sessionToken: __ENV.AWS_SESSION_TOKEN,
42+
})
43+
44+
const sqs = new SQSClient(awsConfig)
45+
const testQueue = 'https://sqs.us-east-1.amazonaws.com/000000000/test-queue'
46+
47+
export default function () {
48+
// If our test queue does not exist, abort the execution.
49+
const queuesResponse = sqs.listQueues()
50+
if (queuesResponse.queueUrls.filter((q) => q === testQueue).length == 0) {
51+
exec.test.abort()
52+
}
53+
54+
// Send message to test queue
55+
sqs.sendMessage(testQueue, JSON.stringify({value: '123'}));
56+
}
57+
```
58+
59+
</CodeGroup>

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/SQSClient/01 sendMessage.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: 'SQSClient.sendMessage()'
3+
description: "SQSClient.sendMessage sends a message to the specified Amazon SQS queue"
4+
excerpt: "SQSClient.sendMessage sends a message to the specified Amazon SQS queue"
5+
---
6+
7+
`SQSClient.sendMessage(queueUrl, messageBody, options)` sends a message to the specified Amazon Simple Queue Service (SQS) queue.
8+
9+
### Parameters
10+
11+
| Name | Type | Description |
12+
| :------------ | :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13+
| `queueUrl` | string | The URL of the Amazon SQS queue to which a message is sent. Queue URLs and names are case-sensitive. |
14+
| `messageBody` | string | The message to send. The minimum size is one character. The maximum size is 256 KB. |
15+
| `options` | object (optional) | Options for the request. Accepted properties are `messageDeduplicationId` (optional string) setting the message deduplication id, and `messageGroupId` (optional string) setting the message group ID for FIFO queues |
16+
17+
### Returns
18+
19+
| Type | Description |
20+
| :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
21+
| `object` | The message that was sent, as an object 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. |
22+
23+
### Example
24+
25+
<CodeGroup labels={[]}>
26+
27+
```javascript
28+
import exec from 'k6/execution'
29+
30+
import { AWSConfig, SQSClient } from 'https://jslib.k6.io/aws/0.7.2/sqs.js'
31+
32+
const awsConfig = new AWSConfig({
33+
region: __ENV.AWS_REGION,
34+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
35+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
36+
sessionToken: __ENV.AWS_SESSION_TOKEN,
37+
})
38+
39+
const sqs = new SQSClient(awsConfig)
40+
const testQueue = 'https://sqs.us-east-1.amazonaws.com/000000000/test-queue'
41+
42+
export default function () {
43+
// If our test queue does not exist, abort the execution.
44+
const queuesResponse = sqs.listQueues()
45+
if (queuesResponse.queueUrls.filter((q) => q === testQueue).length == 0) {
46+
exec.test.abort()
47+
}
48+
49+
// Send message to test queue
50+
sqs.sendMessage(testQueue, JSON.stringify({value: '123'}));
51+
}
52+
```
53+
54+
</CodeGroup>

‎src/data/markdown/docs/20 jslib/01 jslib/01 aws/SQSClient/02 listQueues.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: 'SQSClient.listQueues()'
3+
description: "SQSClient.listQueues retrieves a list of available Amazon SQS queues"
4+
excerpt: "SQSClient.listQueues retrieves a list of available Amazon SQS queues"
5+
---
6+
7+
`SQSClient.listQueues(options)` retrieves a list of available Amazon Simple Queue Service (SQS) queues.
8+
9+
### Parameters
10+
11+
| Name | Type | Description |
12+
| :------------ | :---------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13+
| `options` | object (optional) | Options for the request. Accepted properties are: `queueNamePrefix` (optional string) setting the prefix filter for the returned queue list, `maxResults` (optional number) setting the maximum number of results to include in the response (1 <= `maxResults` <= 1000>), and `nextToken` (optional string) setting the pagination token to request the next set of results. |
14+
15+
### Returns
16+
17+
| Type | Description |
18+
| :---------------------------------------------------------- | :------------------------------------------------------------------------ |
19+
| `object` | An object with an `urls` property containing an array of queue URLs, and an optional `nextToken` containing a pagination token to include in the next request when relevant. |
20+
21+
### Example
22+
23+
<CodeGroup labels={[]}>
24+
25+
```javascript
26+
import exec from 'k6/execution'
27+
28+
import { AWSConfig, SQSClient } from 'https://jslib.k6.io/aws/0.7.2/sqs.js'
29+
30+
const awsConfig = new AWSConfig({
31+
region: __ENV.AWS_REGION,
32+
accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
33+
secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
34+
sessionToken: __ENV.AWS_SESSION_TOKEN,
35+
})
36+
37+
const sqs = new SQSClient(awsConfig)
38+
const testQueue = 'https://sqs.us-east-1.amazonaws.com/000000000/test-queue'
39+
40+
export default function () {
41+
// List all queues in the AWS account
42+
const queuesResponse = sqs.listQueues()
43+
44+
// If our test queue does not exist, abort the execution.
45+
if (queuesResponse.queueUrls.filter((q) => q === testQueue).length == 0) {
46+
exec.test.abort()
47+
}
48+
49+
// Send message to test queue
50+
sqs.sendMessage(testQueue, JSON.stringify({value: '123'}));
51+
}
52+
```
53+
54+
</CodeGroup>

0 commit comments

Comments
 (0)