Skip to content

Commit c55dd63

Browse files
author
Shiyue Cheng
authored
Merge pull request meraki#76 from coreGreenberet/Readme-AsyncIO
added asyncio to the readme
2 parents d49b3f9 + 8ebade6 commit c55dd63

1 file changed

Lines changed: 69 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 69 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -32,23 +32,87 @@ This library's goal is to refresh and supplant the legacy module (this repositor
3232
## Usage
3333
1. Export your API key as an [environment variable](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html), for example:
3434

35-
`export MERAKI_DASHBOARD_API_KEY=093b24e85df15a3e66f1fc359f4c48493eaa1b73`
35+
```shell
36+
export MERAKI_DASHBOARD_API_KEY=093b24e85df15a3e66f1fc359f4c48493eaa1b73
37+
```
3638

3739
2. Alternatively, define your API key as a variable in your source code; this method is not recommended due to its inherent insecurity.
3840

3941
3. Single line of code to import and use the library goes at the top of your script:
4042

41-
`import meraki`
43+
```python
44+
import meraki
45+
```
4246

4347
4. Instantiate the client (API consumer class), optionally specifying any of the parameters available to set:
4448

45-
`dashboard = meraki.DashboardAPI()`
49+
```python
50+
dashboard = meraki.DashboardAPI()
51+
```
4652

4753
5. Make dashboard API calls in your source code, using the format _client.section.operation_, where _client_ is the name you defined in the previous step (**dashboard** above), _section_ is the corresponding group (or tag from the OpenAPI spec) from the [API docs](https://developer.cisco.com/meraki/api/#/rest), and _operation_ is the name (or operation ID from OpenAPI) of the API endpoint. For example, to make a call to get the list of organizations accessible by the API key defined in step 1, use this function call:
4854

49-
`my_orgs = dashboard.organizations.getOrganizations()`
55+
```python
56+
my_orgs = dashboard.organizations.getOrganizations()
57+
```
5058

5159
6. If you were using this module versions 0.34 and prior, that file's functions are included in the _legacy.py_ file, and you can adapt your existing scripts by replacing their `from meraki import meraki` line to `import meraki`
5260
61+
### Examples
62+
You can find fully working example scripts in the **examples** folder.
5363
54-
For a full working script that demos this library, please see and run the **org_wide_clients.py** file included (in **examples** folder). That code collects the clients of all networks, in all orgs to which the key has access. No changes are made, since only GET endpoints are called, and the data is written to local CSV output files.
64+
| Script | Purpose |
65+
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
66+
| **org_wide_clients.py** | That code collects the clients of all networks, in all orgs to which the key has access. No changes are made, since only GET endpoints are called, and the data is written to local CSV output files. |
67+
68+
## AsyncIO
69+
**asyncio** is a library to write concurrent code using the **async/await** syntax. Special thanks to Heimo Stieg ([@coreGreenberet](https://github.com/coreGreenberet)) who has ported the API to asyncio.
70+
71+
The usage is similiar to the sequential version above. However it has has some differences.
72+
73+
1. Export your API key as an [environment variable](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html), for example:
74+
75+
```shell
76+
export MERAKI_DASHBOARD_API_KEY=093b24e85df15a3e66f1fc359f4c48493eaa1b73
77+
```
78+
79+
2. Alternatively, define your API key as a variable in your source code; this method is not recommended due to its inherent insecurity.
80+
81+
3. Single line of code to import and use the library goes at the top of your script:
82+
83+
```python
84+
import meraki.aio
85+
```
86+
87+
4. Instantiate the client (API consumer class), optionally specifying any of the parameters available to set:
88+
89+
```python
90+
async with meraki.aio.AsyncDashboardAPI() as aiomeraki:
91+
```
92+
The **async with** statement is important here to make sure, that the client sessions will be closed after using the api.
93+
94+
5. Make dashboard API calls in your source code, using the format await _client.section.operation_, where _client_ is the name you defined in the previous step (**aiomeraki** above), _section_ is the corresponding group (or tag from the OpenAPI spec) from the [API docs](https://developer.cisco.com/meraki/api/#/rest), and _operation_ is the name (or operation ID from OpenAPI) of the API endpoint. For example, to make a call to get the list of organizations accessible by the API key defined in step 1, use this function call:
95+
96+
```python
97+
my_orgs = await aiomeraki.organizations.getOrganizations()
98+
```
99+
6. Run everything inside an event loop.
100+
```python
101+
import asyncio
102+
103+
if __name__ == "__main__":
104+
loop = asyncio.get_event_loop()
105+
loop.run_until_complete(my_async_entry_point())
106+
107+
# if you are using Python 3.7+ you can also simply
108+
# use the following line instead of the two lines above
109+
asyncio.run(my_async_entry_point())
110+
```
111+
112+
113+
### Examples
114+
You can find fully working example scripts in the **examples** folder.
115+
| Script | Purpose |
116+
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
117+
| **aio_org_wide_clients.py** | That code is a asyncio port from org_wide_clients.py and collects the clients of all networks, in all orgs to which the key has access. No changes are made, since only GET endpoints are called, and the data is written to local CSV output files. |
118+
| **aio_ips2firewall.py** | That code will collect the source IP of security events and creates L7 firewall rules to block them. `usage: aio_ips2firewall.py [-h] -o ORGANIZATIONS [ORGANIZATIONS ...] [-f FILTER] [-s] [-d DAYS]` |

0 commit comments

Comments
 (0)