Added v1

- renamed previous "meraki" folder to "meraki_v0"
- added "meraki_v1" for v1 beta library functionality
- added examples for org-wide clients report for v1
- included several new API endpoints/features released recently

Author: Shiyue Cheng

README.md

@@ -1,33 +1,34 @@
 # 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/):
+The Meraki Dashboard API Python library provides all current Meraki [Dashboard API](https://developer.cisco.com/docs/meraki-api-v1) 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:
+While you can make direct HTTP requests to dashboard API in any programming language or REST API client, using a client library can make it easier for you to focus on your specific use case, without the overhead of having to write functions to handle the dashboard API calls. The Python library can also take care of error handling, logging, retries, and other convenient processes and options for you automatically.
 
-* Support for all API endpoints, as it uses the [OpenAPI specification](https://api.meraki.com/api/v0/openapiSpec) to generate source code
+* Support for all API endpoints, as it uses the [OpenAPI specification](https://api.meraki.com/api/v1/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
+* Automatic retries upon 429 rate limit errors, using the [`Retry-After` field](https://developer.cisco.com/docs/meraki-api-v1/#!rate-limit) 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)
+* Tweak settings such as maximum retries, certificate path, suppress logging, and other options
 * 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
+* Includes the legacy module's (version 0.34 and prior) 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))
+3. Install the latest version of [Python 3](ttps://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:
+4. 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`
     * If _meraki_ was previously installed, you can upgrade with `pip install --upgrade meraki` or `pip3 install --upgrade meraki`
+    * You can specify the version of the library, for example `pip install meraki==0.100.2` for v0 or `pip install meraki==1.0.0b1` for v1
 
 ## 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:
@@ -50,7 +51,7 @@ This library's goal is to refresh and supplant the legacy module (this repositor
     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:
+5. Make dashboard API calls in your source code, using the format _client.scope.operation_, where _client_ is the name you defined in the previous step (**dashboard** above), _scope_ is the corresponding scope that represents the first tag from the OpenAPI spec, and _operation_ is the operation 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:
 
     ```python
     my_orgs = dashboard.organizations.getOrganizations()

examples/aio_ips2firewall.py examples/aio_ips2firewall_v0.pyexamples/aio_ips2firewall.py renamed to examples/aio_ips2firewall_v0.py

@@ -81,9 +81,10 @@ async def listOrganization(aiomeraki: meraki.aio.AsyncDashboardAPI, org):
 
     # 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 = ['id', 'mac', 'description', 'ip', 'ip6', 'ip6Local', 'user', 'firstSeen', 'lastSeen', 'manufacturer', 'os', 'recentDeviceSerial', 'recentDeviceName', 'recentDeviceMac', 'ssid', 'vlan', 'switchport', 'usage', 'status', 'notes', 'smInstalled', 'groupPolicy8021x']
     field_names.insert(0, "Network Name")
     field_names.insert(1, "Network ID")
+    
     csv_writer = csv.DictWriter(
         output_file,
         field_names,

examples/aio_org_wide_clients.py examples/aio_org_wide_clients_v0.pyexamples/aio_org_wide_clients.py renamed to examples/aio_org_wide_clients_v0.py

@@ -0,0 +1,138 @@
+import csv
+from datetime import datetime
+import os
+import asyncio
+
+import meraki.aio
+
+# Either input your API key below, or set an environment variable
+# for example, in Terminal on macOS:  export MERAKI_DASHBOARD_API_KEY=093b24e85df15a3e66f1fc359f4c48493eaa1b73
+api_key = ""
+
+
+async def listNetworkClients(aiomeraki: meraki.aio.AsyncDashboardAPI, folder_name, network):
+    print(f'Finding clients in network {network["name"]}')
+    try:
+        # Get list of clients on network, filtering on timespan of last 14 days
+        clients = await aiomeraki.networks.getNetworkClients(
+            network["id"],
+            timespan=60 * 60 * 24 * 14,
+            perPage=1000,
+            total_pages="all",
+        )
+    except meraki.AsyncAPIError 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'{network["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"Successfully output {len(clients)} clients' data to file {file_name}"
+            )
+            return network["name"], field_names
+    return network["name"], None
+
+
+async def listOrganization(aiomeraki: meraki.aio.AsyncDashboardAPI, org):
+    print(f'Analyzing organization {org["name"]}:')
+    org_id = org["id"]
+
+    # Get list of networks in organization
+    try:
+        networks = await aiomeraki.organizations.getOrganizationNetworks(org_id)
+    except meraki.AsyncAPIError as e:
+        print(f"Meraki API error: {e}")
+        return org["name"]
+    except Exception as e:
+        print(f"some other error: {e}")
+        return org["name"]
+
+    # 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)
+    print(f"Iterating through {total} networks in organization {org_id}")
+
+    # create a list of all networks in the organization so we can call them all concurrently
+    networkClientsTasks = [listNetworkClients(aiomeraki, folder_name, net) for net in networks]
+    for task in asyncio.as_completed(networkClientsTasks):
+        networkname, field_names = await task
+        print(f"finished network: {networkname}")
+
+    # Stitch together one consolidated CSV per org
+    output_file = open(f"{folder_name}.csv", mode="w", newline="\n")
+    field_names = ['id', 'mac', 'description', 'ip', 'ip6', 'ip6Local', 'user', 'firstSeen', 'lastSeen', 'manufacturer', 'os', 'recentDeviceSerial', 'recentDeviceName', 'recentDeviceMac', 'ssid', 'vlan', 'switchport', 'usage', 'status', 'notes', 'smInstalled', 'groupPolicy8021x']
+    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)
+    return org["name"]
+
+
+async def main():
+    # Instantiate a Meraki dashboard API session
+    # NOTE: you have to use "async with" so that the session will be closed correctly at the end of the usage
+    async with meraki.aio.AsyncDashboardAPI(
+            api_key,
+            base_url="https://api.meraki.com/api/v1",
+            log_file_prefix=__file__[:-3],
+            print_console=False,
+    ) as aiomeraki:
+        # Get list of organizations to which API key has access
+        organizations = await aiomeraki.organizations.getOrganizations()
+
+        # create a list of all organizations so we can call them all concurrently
+        organizationTasks = [listOrganization(aiomeraki, org) for org in organizations]
+        for task in asyncio.as_completed(organizationTasks):
+            # as_completed returns an iterator, so we just have to await the iterator and not call it
+            organizationName = await task
+            print(f"finished organization: {organizationName}")
+
+        print("Script complete!")
+
+
+if __name__ == "__main__":
+    loop = asyncio.get_event_loop()
+    loop.run_until_complete(main())

examples/aio_org_wide_clients_v1.py

@@ -15,6 +15,7 @@ def main():
     dashboard = meraki.DashboardAPI(
         api_key='',
         base_url='https://api-mp.meraki.com/api/v0/',
+        output_log=True,
         log_file_prefix=os.path.basename(__file__)[:-3],
         log_path='',
         print_console=False
@@ -33,6 +34,9 @@ def main():
             networks = dashboard.networks.getOrganizationNetworks(org_id)
         except meraki.APIError as e:
             print(f'Meraki API error: {e}')
+            print(f'status code = {e.status}')
+            print(f'reason = {e.reason}')
+            print(f'error = {e.message}')
             continue
         except Exception as e:
             print(f'some other error: {e}')
@@ -55,6 +59,9 @@ def main():
                 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}')
+                print(f'status code = {e.status}')
+                print(f'reason = {e.reason}')
+                print(f'error = {e.message}')
             except Exception as e:
                 print(f'some other error: {e}')
             else:
@@ -74,9 +81,10 @@ def main():
 
         # 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')
+        field_names = ['id', 'mac', 'description', 'ip', 'ip6', 'ip6Local', 'user', 'firstSeen', 'lastSeen', 'manufacturer', 'os', 'recentDeviceSerial', 'recentDeviceName', 'recentDeviceMac', 'ssid', 'vlan', 'switchport', 'usage', 'status', 'notes', 'smInstalled', 'groupPolicy8021x']
+        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:

examples/org_wide_clients.py examples/org_wide_clients_v0.pyexamples/org_wide_clients.py renamed to examples/org_wide_clients_v0.py

@@ -0,0 +1,106 @@
+import csv
+from datetime import datetime
+import os
+
+import meraki
+
+# Either input your API key below by uncommenting line 10 and changing line 16 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='',
+        base_url='https://api-mp.meraki.com/api/v1/',
+        output_log=True,
+        log_file_prefix=os.path.basename(__file__)[:-3],
+        log_path='',
+        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.organizations.getOrganizationNetworks(org_id)
+        except meraki.APIError as e:
+            print(f'Meraki API error: {e}')
+            print(f'status code = {e.status}')
+            print(f'reason = {e.reason}')
+            print(f'error = {e.message}')
+            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.networks.getNetworkClients(net['id'], timespan=60*60*24*14, perPage=1000, total_pages='all')
+            except meraki.APIError as e:
+                print(f'Meraki API error: {e}')
+                print(f'status code = {e.status}')
+                print(f'reason = {e.reason}')
+                print(f'error = {e.message}')
+            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 = ['id', 'mac', 'description', 'ip', 'ip6', 'ip6Local', 'user', 'firstSeen', 'lastSeen', 'manufacturer', 'os', 'recentDeviceSerial', 'recentDeviceName', 'recentDeviceMac', 'ssid', 'vlan', 'switchport', 'usage', 'status', 'notes', 'smInstalled', 'groupPolicy8021x']
+        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}')