Skip to content

Commit 03be111

Browse files
trivikrtrivikr
authored
feat(clients): update README with documentation, usage and more (#1907)
1 parent 1308721 commit 03be111

File tree

257 files changed

+55831
-453
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

257 files changed

+55831
-453
lines changed

Diff for: ‎clients/client-accessanalyzer/README.md

+204-1
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,207 @@
33
[![NPM version](https://img.shields.io/npm/v/@aws-sdk/client-accessanalyzer/latest.svg)](https://www.npmjs.com/package/@aws-sdk/client-accessanalyzer)
44
[![NPM downloads](https://img.shields.io/npm/dm/@aws-sdk/client-accessanalyzer.svg)](https://www.npmjs.com/package/@aws-sdk/client-accessanalyzer)
55

6-
For SDK usage, please step to [SDK readme](https://github.com/aws/aws-sdk-js-v3).
6+
## Description
7+
8+
AWS SDK for JavaScript AccessAnalyzer Client for Node.js, Browser and React Native.
9+
10+
<p>AWS IAM Access Analyzer helps identify potential resource-access risks by enabling you to identify
11+
any policies that grant access to an external principal. It does this by using logic-based
12+
reasoning to analyze resource-based policies in your AWS environment. An external principal
13+
can be another AWS account, a root user, an IAM user or role, a federated user, an AWS
14+
service, or an anonymous user. This guide describes the AWS IAM Access Analyzer operations that you can
15+
call programmatically. For general information about Access Analyzer, see the <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html">AWS IAM Access Analyzer section of the IAM User Guide</a>.</p>
16+
<p>To start using Access Analyzer, you first need to create an analyzer.</p>
17+
18+
## Installing
19+
20+
To install the this package, simply type add or install @aws-sdk/client-accessanalyzer
21+
using your favorite package manager:
22+
23+
- `npm install @aws-sdk/client-accessanalyzer`
24+
- `yarn add @aws-sdk/client-accessanalyzer`
25+
- `pnpm add @aws-sdk/client-accessanalyzer`
26+
27+
## Getting Started
28+
29+
### Import
30+
31+
The AWS SDK is modulized by clients and commands.
32+
To send a request, you only need to import the `AccessAnalyzerClient` and
33+
the commands you need, for example `CreateAnalyzerCommand`:
34+
35+
```js
36+
// ES5 example
37+
const { AccessAnalyzerClient, CreateAnalyzerCommand } = require("@aws-sdk/client-accessanalyzer");
38+
```
39+
40+
```ts
41+
// ES6+ example
42+
import { AccessAnalyzerClient, CreateAnalyzerCommand } from "@aws-sdk/client-accessanalyzer";
43+
```
44+
45+
### Usage
46+
47+
To send a request, you:
48+
49+
- Initiate client with configuration (e.g. credentials, region).
50+
- Initiate command with input parameters.
51+
- Call `send` operation on client with command object as input.
52+
- If you are using a custom http handler, you may call `destroy()` to close open connections.
53+
54+
```js
55+
// a client can be shared by difference commands.
56+
const client = new AccessAnalyzerClient({ region: "REGION" });
57+
58+
const params = {
59+
/** input parameters */
60+
};
61+
const command = new CreateAnalyzerCommand(params);
62+
```
63+
64+
#### Async/await
65+
66+
We recommend using [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)
67+
operator to wait for the promise returned by send operation as follows:
68+
69+
```js
70+
// async/await.
71+
try {
72+
const data = await client.send(command);
73+
// process data.
74+
} catch (error) {
75+
// error handling.
76+
} finally {
77+
// finally.
78+
}
79+
```
80+
81+
Async-await is clean, concise, intuitive, easy to debug and has better error handling
82+
as compared to using Promise chains or callbacks.
83+
84+
#### Promises
85+
86+
You can also use [Promise chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Using_promises#chaining)
87+
to execute send operation.
88+
89+
```js
90+
client.send(command).then(
91+
(data) => {
92+
// process data.
93+
},
94+
(error) => {
95+
// error handling.
96+
}
97+
);
98+
```
99+
100+
Promises can also be called using `.catch()` and `.finally()` as follows:
101+
102+
```js
103+
client
104+
.send(command)
105+
.then((data) => {
106+
// process data.
107+
})
108+
.catch((error) => {
109+
// error handling.
110+
})
111+
.finally(() => {
112+
// finally.
113+
});
114+
```
115+
116+
#### Callbacks
117+
118+
We do not recommend using callbacks because of [callback hell](http://callbackhell.com/),
119+
but they are supported by the send operation.
120+
121+
```js
122+
// callbacks.
123+
client.send(command, (err, data) => {
124+
// proccess err and data.
125+
});
126+
```
127+
128+
#### v2 compatible style
129+
130+
The client can also send requests using v2 compatible style.
131+
However, it results in a bigger bundle size and may be dropped in next major version. More details in the blog post
132+
on [modular packages in AWS SDK for JavaScript](https://aws.amazon.com/blogs/developer/modular-packages-in-aws-sdk-for-javascript/)
133+
134+
```ts
135+
import * as AWS from "@aws-sdk/client-accessanalyzer";
136+
const client = new AWS.AccessAnalyzer({ region: "REGION" });
137+
138+
// async/await.
139+
try {
140+
const data = client.createAnalyzer(params);
141+
// process data.
142+
} catch (error) {
143+
// error handling.
144+
}
145+
146+
// Promises.
147+
client
148+
.createAnalyzer(params)
149+
.then((data) => {
150+
// process data.
151+
})
152+
.catch((error) => {
153+
// error handling.
154+
});
155+
156+
// callbacks.
157+
client.createAnalyzer(params, (err, data) => {
158+
// proccess err and data.
159+
});
160+
```
161+
162+
### Troubleshooting
163+
164+
When the service returns an exception, the error will include the exception information,
165+
as well as response metadata (e.g. request id).
166+
167+
```js
168+
try {
169+
const data = await client.send(command);
170+
// process data.
171+
} catch (error) {
172+
const { requestId, cfId, extendedRequestId } = error.$metadata;
173+
console.log({ requestId, cfId, extendedRequestId });
174+
/**
175+
* The keys within exceptions are also parsed.
176+
* You can access them by specifying exception names:
177+
* if (error.name === 'SomeServiceException') {
178+
* const value = error.specialKeyInException;
179+
* }
180+
*/
181+
}
182+
```
183+
184+
## Getting Help
185+
186+
Please use these community resources for getting help.
187+
We use the GitHub issues for tracking bugs and feature requests, but have limited bandwidth to address them.
188+
189+
- Visit [Developer Guide](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html)
190+
or [API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/index.html).
191+
- Check out the blog posts tagged with [`aws-sdk-js`](https://aws.amazon.com/blogs/developer/tag/aws-sdk-js/)
192+
on AWS Developer Blog.
193+
- Ask a question on [StackOverflow](https://stackoverflow.com/questions/tagged/aws-sdk-js) and tag it with `aws-sdk-js`.
194+
- Join the AWS JavaScript community on [gitter](https://gitter.im/aws/aws-sdk-js-v3).
195+
- If it turns out that you may have found a bug, please [open an issue](https://github.com/aws/aws-sdk-js-v3/issues/new/choose).
196+
197+
To test your universal JavaScript code in Node.js, browser and react-native environments,
198+
visit our [code samples repo](https://github.com/aws-samples/aws-sdk-js-tests).
199+
200+
## Contributing
201+
202+
This client code is generated automatically. Any modifications will be overwritten the next time the `@aws-sdk/client-accessanalyzer` package is updated.
203+
To contribute to client you can check our [generate clients scripts](https://github.com/aws/aws-sdk-js-v3/tree/master/scripts/generate-clients).
204+
205+
## License
206+
207+
This SDK is distributed under the
208+
[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0),
209+
see LICENSE for more information.

0 commit comments

Comments
 (0)