major revamp of the dashboard API library

Author: Shiyue Cheng

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Cisco Systems, Inc. and/or its affiliates  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,33 +1,51 @@
-Python 3.6 module providing all current Meraki [Dashboard API](https://dashboard.meraki.com/api_docs) calls to interface with the Cisco Meraki cloud-managed IT solutions.
-Also available via [PIP](https://pypi.python.org/pypi/meraki/).
-
-
-## Initial Setup
-* Enable APIs in your Meraki dashboard and obtain an APIKey: [Instructions](https://documentation.meraki.com/zGeneral_Administration/Other_Topics/The_Cisco_Meraki_Dashboard_API) 
-  * Keep your APIKey safe and secure.  It is similar to a password for your dashboard.  If publishing your Python programs to a wider audience, please research secure handling of APIKeys.
-* Although the Meraki API can be accessed in various ways, this module uses Python3.  [Get started with Python](https://wiki.python.org/moin/BeginnersGuide/NonProgrammers)
-* After Python is installed, prepare your environment:
-  * Use pip (or alternative such as easy_install) to install required packages:
-    * pip install requests meraki
-* You are now ready to create your first script:
-  * create a new file and name it with python extension, e.g., meraki_hello_world.py
-  * import the meraki api into your script, e.g.,  from meraki import meraki
-  * use the meraki API to interact with your dashboard
-  
-## Example
-
-```python
-from meraki import meraki
-
-apikey = "jkhsfsdhk32424******example*****jlasdfsdfl3245345"
-myOrgs = meraki.myorgaccess(apikey)
-print(myOrgs)
-```
-
-## Useful API calls to get started
-
-```python
-myNetworks = meraki.getnetworklist(apikey, orgid)
-deviceList = meraki.getnetworkdevices(apikey, networkid)
-clientList = meraki.getclients(apikey,serialnum)
-```
+# Meraki Dashboard API Python Library
+
+The new Meraki Dashboard API Python library provides all current Meraki [Dashboard API](https://api.meraki.com/api_docs) calls to interface with the Cisco Meraki cloud-managed platform. The library is supported on Python 3.6 or above, and you can install it via [PyPI](https://pypi.org/project/meraki/):
+
+    pip install meraki
+
+## Features
+
+This library's goal is to refresh and supplant the legacy module (this repository versions 0.34 and prior) as well as the now-deprecated [SDK](https://github.com/meraki/meraki-python-sdk). Here are some of the features in this revamped library:
+
+* Support for all API endpoints, as it uses the [OpenAPI specification](https://api.meraki.com/api/v0/openapiSpec) to generate source code
+* Log all API requests made to a local file as well as on-screen console
+* Automatic retries upon 429 rate limit errors, using the [`Retry-After` field](https://developer.cisco.com/meraki/api/#/rest/guides/rate-limit-errors) within response headers
+* Get all (or a specified number of) pages of data with built-in pagination control
+* Tweak settings such as the default base URL (for example, to use with V1 and/or mega-proxy)
+* Simulate POST/PUT/DELETE calls to preview first, so that network configuration does not get changed
+* Includes the legacy module's functions for backward compatibility
+
+## Setup
+
+1. Enable API access in your Meraki dashboard organization and obtain an API key ([instructions](https://documentation.meraki.com/zGeneral_Administration/Other_Topics/The_Cisco_Meraki_Dashboard_API))
+
+2. Keep your API key safe and secure, as it is similar to a password for your dashboard. If publishing your Python code to a wider audience, please research secure handling of API keys.
+
+3. Although the Meraki dashboard API, as a REST API, can be accessed in various ways, this library uses Python 3.6+. ([get started with Python](https://wiki.python.org/moin/BeginnersGuide/NonProgrammers))
+
+4. After Python 3 is installed, use _pip_ (or an alternative such as _easy_install_) to install the library:
+    * `pip install meraki`
+    * If you have both Python3 and Python2 installed, you may need to use `pip3 install meraki`
+
+## Usage
+1. Export your API key as an [environment variable](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html), for example:
+
+    `export MERAKI_DASHBOARD_API_KEY=093b24e85df15a3e66f1fc359f4c48493eaa1b73`
+
+2. Alternatively, define your API key as a variable in your source code; this method is not recommended due to its inherent insecurity.
+
+3. Single line of code to import and use the library goes at the top of your script:
+
+    `import meraki`
+
+4. Instantiate the client (API consumer class), optionally specifying any of the parameters available to set:
+
+    `dashboard = meraki.DashboardAPI()`
+
+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:
+
+    `my_orgs = dashboard.organizations.getOrganizations()`
+
+
+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.

examples/org_wide_clients.py

@@ -0,0 +1,92 @@
+import csv
+from datetime import datetime
+import os
+
+import meraki
+
+# Either input your API key below by uncommenting line 10 and changing line 15 to api_key=api_key,
+# or set an environment variable (preferred) to define your API key. The former is insecure and not recommended.
+# For example, in Linux/macOS:  export MERAKI_DASHBOARD_API_KEY=093b24e85df15a3e66f1fc359f4c48493eaa1b73
+# api_key = '093b24e85df15a3e66f1fc359f4c48493eaa1b73'
+
+
+def main():
+    # Instantiate a Meraki dashboard API session
+    dashboard = meraki.DashboardAPI(api_key=None, base_url='https://api.meraki.com/api/v0/', log_file_prefix=__file__[:-3], print_console=False)
+
+    # Get list of organizations to which API key has access
+    organizations = dashboard.organizations.getOrganizations()
+
+    # Iterate through list of orgs
+    for org in organizations:
+        print(f'\nAnalyzing organization {org["name"]}:')
+        org_id = org['id']
+
+        # Get list of networks in organization
+        try:
+            networks = dashboard.networks.getOrganizationNetworks(org_id)
+        except meraki.APIError as e:
+            print(f'Meraki API error: {e}')
+            continue
+        except Exception as e:
+            print(f'some other error: {e}')
+            continue
+        
+        # Create local folder
+        todays_date = f'{datetime.now():%Y-%m-%d}'
+        folder_name = f'Org {org_id} clients {todays_date}'
+        if folder_name not in os.listdir():
+            os.mkdir(folder_name)
+
+        # Iterate through networks
+        total = len(networks)
+        counter = 1
+        print(f'  - iterating through {total} networks in organization {org_id}')
+        for net in networks:
+            print(f'Finding clients in network {net["name"]} ({counter} of {total})')
+            try:
+                # Get list of clients on network, filtering on timespan of last 14 days
+                clients = dashboard.clients.getNetworkClients(net['id'], timespan=60*60*24*14, perPage=1000, total_pages='all')
+            except meraki.APIError as e:
+                print(f'Meraki API error: {e}')
+            except Exception as e:
+                print(f'some other error: {e}')
+            else:
+                if clients:
+                    # Write to file
+                    file_name = f'{net["name"]}.csv'
+                    output_file = open(f'{folder_name}/{file_name}', mode='w', newline='\n')
+                    field_names = clients[0].keys()
+                    csv_writer = csv.DictWriter(output_file, field_names, delimiter=',', quotechar='"',
+                                                quoting=csv.QUOTE_ALL)
+                    csv_writer.writeheader()
+                    csv_writer.writerows(clients)
+                    output_file.close()
+                    print(f'  - found {len(clients)}')
+
+            counter += 1
+
+        # Stitch together one consolidated CSV per org
+        output_file = open(f'{folder_name}.csv', mode='w', newline='\n')
+        field_names = list(field_names)
+        field_names.insert(0, 'Network Name')
+        field_names.insert(1, 'Network ID')
+        csv_writer = csv.DictWriter(output_file, field_names, delimiter=',', quotechar='"', quoting=csv.QUOTE_ALL)
+        csv_writer.writeheader()
+        for net in networks:
+            file_name = f'{net["name"]}.csv'
+            if file_name in os.listdir(folder_name):
+                with open(f'{folder_name}/{file_name}') as input_file:
+                    csv_reader = csv.DictReader(input_file, delimiter=',', quotechar='"', quoting=csv.QUOTE_ALL)
+                    next(csv_reader)
+                    for row in csv_reader:
+                        row['Network Name'] = net['name']
+                        row['Network ID'] = net['id']
+                        csv_writer.writerow(row)
+
+
+if __name__ == '__main__':
+    start_time = datetime.now()
+    main()
+    end_time = datetime.now()
+    print(f'\nScript complete, total runtime {end_time - start_time}')