Updated with v1.0.0b3 release

Author: Shiyue Cheng

README.md

@@ -28,8 +28,10 @@ While you can make direct HTTP requests to dashboard API in any programming lang
     * `pip install meraki`
     * If you have both Python3 and Python2 installed, you may need to use `pip3` (so `pip3 install meraki`) along with `python3` on your system
     * If _meraki_ was previously installed, you can upgrade to the latest stable (non-beta) release with `pip install --upgrade meraki`
-    * You can specify the version of the library, for example `pip install meraki==0.110.0` for v0 or `pip install meraki==1.0.0b3` for v1 beta
-    * To see the [release history](https://pypi.org/project/meraki/#history), you can also use `pip install meraki==` without including a version number
+
+5. Meraki dashboard API v1 is currently in beta, so if you clone this repository and want to use v1 locally, rename the folder _meraki_v1_ to _meraki_, replacing the v0 contents there. You can also specify the version of the library when installing with _pip_:
+    * For example, `pip install meraki==0.110.0` for v0 or `pip install meraki==1.0.0b3` for v1 beta
+    * To see the full [release history](https://pypi.org/project/meraki/#history), you can also use `pip install meraki==` without including a version number
 
 ## 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:

meraki/aio/rest_session.py

@@ -96,7 +96,7 @@ def __init__(
         # Check base URL
         if 'v1' in self._base_url:
             sys.exit(f'If you want to use the Python library with v1 paths ({self._base_url} was configured as the base'
-                     f' URL), then install the v1 library. For example: pip install meraki==1.0.0b1')
+                     f' URL), then install the v1 library. See the "Setup" section @ https://github.com/meraki/dashboard-api-python/')
         elif self._base_url[-1] == '/':
             self._base_url = self._base_url[:-1]
 

meraki_v1/__init__.py

@@ -17,10 +17,11 @@
 from .config import (
     API_KEY_ENVIRONMENT_VARIABLE, DEFAULT_BASE_URL, SINGLE_REQUEST_TIMEOUT, CERTIFICATE_PATH, WAIT_ON_RATE_LIMIT,
     NGINX_429_RETRY_WAIT_TIME, ACTION_BATCH_RETRY_WAIT_TIME, RETRY_4XX_ERROR, RETRY_4XX_ERROR_WAIT_TIME,
-    MAXIMUM_RETRIES, OUTPUT_LOG, LOG_PATH, LOG_FILE_PREFIX, PRINT_TO_CONSOLE, SUPPRESS_LOGGING, SIMULATE_API_CALLS
+    MAXIMUM_RETRIES, OUTPUT_LOG, LOG_PATH, LOG_FILE_PREFIX, PRINT_TO_CONSOLE, SUPPRESS_LOGGING, SIMULATE_API_CALLS,
+    BE_GEO_ID, MERAKI_PYTHON_SDK_CALLER
 )
 
-__version__ = '1.0.0b1'
+__version__ = '1.0.0b3'
 
 class DashboardAPI(object):
     """
@@ -53,7 +54,7 @@ def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, single_request_timeo
                  retry_4xx_error=RETRY_4XX_ERROR, retry_4xx_error_wait_time=RETRY_4XX_ERROR_WAIT_TIME,
                  maximum_retries=MAXIMUM_RETRIES, output_log=OUTPUT_LOG, log_path=LOG_PATH,
                  log_file_prefix=LOG_FILE_PREFIX, print_console=PRINT_TO_CONSOLE, suppress_logging=SUPPRESS_LOGGING,
-                 simulate=SIMULATE_API_CALLS, be_geo_id='', caller=''):
+                 simulate=SIMULATE_API_CALLS, be_geo_id=BE_GEO_ID, caller=MERAKI_PYTHON_SDK_CALLER):
         # Check API key
         api_key = api_key or os.environ.get(API_KEY_ENVIRONMENT_VARIABLE)
         if not api_key:

meraki_v1/aio/__init__.py

@@ -17,10 +17,9 @@
     API_KEY_ENVIRONMENT_VARIABLE, DEFAULT_BASE_URL, SINGLE_REQUEST_TIMEOUT, CERTIFICATE_PATH, WAIT_ON_RATE_LIMIT,
     NGINX_429_RETRY_WAIT_TIME, ACTION_BATCH_RETRY_WAIT_TIME, RETRY_4XX_ERROR, RETRY_4XX_ERROR_WAIT_TIME,
     MAXIMUM_RETRIES, OUTPUT_LOG, LOG_PATH, LOG_FILE_PREFIX, PRINT_TO_CONSOLE, SUPPRESS_LOGGING, SIMULATE_API_CALLS,
-    AIO_MAXIMUM_CONCURRENT_REQUESTS
+    AIO_MAXIMUM_CONCURRENT_REQUESTS, BE_GEO_ID, MERAKI_PYTHON_SDK_CALLER
 )
 
-__version__ = '1.0.0b1'
 
 class AsyncDashboardAPI:
     """
@@ -43,6 +42,8 @@ class AsyncDashboardAPI:
     - suppress_logging (boolean): disable all logging? you're on your own then!
     - simulate (boolean): simulate POST/PUT/DELETE calls to prevent changes?
     - maximum_concurrent_requests (integer): number of concurrent API requests for asynchronous class
+    - be_geo_id (string): optional partner identifier for API usage tracking; can also be set as an environment variable BE_GEO_ID
+    - caller (string): optional identifier for API usage tracking; can also be set as an environment variable MERAKI_PYTHON_SDK_CALLER
     """
 
     def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, single_request_timeout=SINGLE_REQUEST_TIMEOUT,
@@ -52,11 +53,18 @@ def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, single_request_timeo
                  retry_4xx_error=RETRY_4XX_ERROR, retry_4xx_error_wait_time=RETRY_4XX_ERROR_WAIT_TIME,
                  maximum_retries=MAXIMUM_RETRIES, output_log=OUTPUT_LOG, log_path=LOG_PATH,
                  log_file_prefix=LOG_FILE_PREFIX, print_console=PRINT_TO_CONSOLE, suppress_logging=SUPPRESS_LOGGING,
-                 simulate=SIMULATE_API_CALLS, maximum_concurrent_requests=AIO_MAXIMUM_CONCURRENT_REQUESTS):
+                 simulate=SIMULATE_API_CALLS, maximum_concurrent_requests=AIO_MAXIMUM_CONCURRENT_REQUESTS,
+                 be_geo_id=BE_GEO_ID, caller=MERAKI_PYTHON_SDK_CALLER):
         # Check API key
         api_key = api_key or os.environ.get(API_KEY_ENVIRONMENT_VARIABLE)
         if not api_key:
             raise APIKeyError()
+        
+        # Pull the BE GEO ID from an environment variable if present
+        be_geo_id = be_geo_id or os.environ.get('BE_GEO_ID')
+
+        # Pull the caller from an environment variable if present
+        caller = caller or os.environ.get('MERAKI_PYTHON_SDK_CALLER')
 
         # Configure logging
         if not suppress_logging:
@@ -98,7 +106,9 @@ def __init__(self, api_key=None, base_url=DEFAULT_BASE_URL, single_request_timeo
             retry_4xx_error_wait_time=retry_4xx_error_wait_time,
             maximum_retries=maximum_retries,
             simulate=simulate,
-            maximum_concurrent_requests=maximum_concurrent_requests
+            maximum_concurrent_requests=maximum_concurrent_requests,
+            be_geo_id=be_geo_id,
+            caller=caller,
         )
 
         # API endpoints by section

meraki_v1/aio/api/__init__.py

@@ -3,6 +3,22 @@ def __init__(self, session):
         super().__init__()
         self._session = session
 
+    async def getDeviceApplianceDhcpSubnets(self, serial: str):
+        """
+        **Return the DHCP subnet information for an appliance**
+        https://developer.cisco.com/docs/meraki-api-v1/#!get-device-appliance-dhcp-subnets
+        
+        - serial (string)
+        """
+
+        metadata = {
+            'tags': ['appliance', 'monitor', 'dhcp', 'subnets'],
+            'operation': 'getDeviceApplianceDhcpSubnets',
+        }
+        resource = f'/devices/{serial}/appliance/dhcp/subnets'
+
+        return await self._session.get(metadata, resource)
+
     async def getDeviceAppliancePerformance(self, serial: str):
         """
         **Return the performance score for a single device. Only primary MX devices supported. If no data is available, a 204 error code is returned.**
@@ -1186,6 +1202,99 @@ async def updateNetworkApplianceVpnSiteToSiteVpn(self, networkId: str, mode: str
 
         return await self._session.put(metadata, resource, payload)
 
+    async def getNetworkApplianceWarmSpare(self, networkId: str):
+        """
+        **Return MX warm spare settings**
+        https://developer.cisco.com/docs/meraki-api-v1/#!get-network-appliance-warm-spare
+        
+        - networkId (string)
+        """
+
+        metadata = {
+            'tags': ['appliance', 'configure', 'warmSpare'],
+            'operation': 'getNetworkApplianceWarmSpare',
+        }
+        resource = f'/networks/{networkId}/appliance/warmSpare'
+
+        return await self._session.get(metadata, resource)
+
+    async def updateNetworkApplianceWarmSpare(self, networkId: str, enabled: bool, **kwargs):
+        """
+        **Update MX warm spare settings**
+        https://developer.cisco.com/docs/meraki-api-v1/#!update-network-appliance-warm-spare
+        
+        - networkId (string)
+        - enabled (boolean): Enable warm spare
+        - spareSerial (string): Serial number of the warm spare appliance
+        - uplinkMode (string): Uplink mode, either virtual or public
+        - virtualIp1 (string): The WAN 1 shared IP
+        - virtualIp2 (string): The WAN 2 shared IP
+        """
+
+        kwargs.update(locals())
+
+        metadata = {
+            'tags': ['appliance', 'configure', 'warmSpare'],
+            'operation': 'updateNetworkApplianceWarmSpare',
+        }
+        resource = f'/networks/{networkId}/appliance/warmSpare'
+
+        body_params = ['enabled', 'spareSerial', 'uplinkMode', 'virtualIp1', 'virtualIp2']
+        payload = {k: v for (k, v) in kwargs.items() if k in body_params}
+
+        return await self._session.put(metadata, resource, payload)
+
+    async def swapNetworkApplianceWarmSpare(self, networkId: str):
+        """
+        **Swap MX primary and warm spare appliances**
+        https://developer.cisco.com/docs/meraki-api-v1/#!swap-network-appliance-warm-spare
+        
+        - networkId (string)
+        """
+
+        metadata = {
+            'tags': ['appliance', 'configure', 'warmSpare'],
+            'operation': 'swapNetworkApplianceWarmSpare',
+        }
+        resource = f'/networks/{networkId}/appliance/warmSpare/swap'
+
+        return await self._session.post(metadata, resource)
+
+    async def getOrganizationApplianceSecurityEvents(self, organizationId: str, total_pages=1, direction='next', **kwargs):
+        """
+        **List the security events for an organization**
+        https://developer.cisco.com/docs/meraki-api-v1/#!get-organization-appliance-security-events
+        
+        - organizationId (string)
+        - total_pages (integer or string): total number of pages to retrieve, -1 or "all" for all pages
+        - direction (string): direction to paginate, either "next" (default) or "prev" page
+        - t0 (string): The beginning of the timespan for the data. The maximum lookback period is 365 days from today.
+        - t1 (string): The end of the timespan for the data. t1 can be a maximum of 365 days after t0.
+        - timespan (number): The timespan for which the information will be fetched. If specifying timespan, do not specify parameters t0 and t1. The value must be in seconds and be less than or equal to 365 days. The default is 31 days.
+        - perPage (integer): The number of entries per page returned. Acceptable range is 3 - 1000. Default is 100.
+        - startingAfter (string): A token used by the server to indicate the start of the page. Often this is a timestamp or an ID but it is not limited to those. This parameter should not be defined by client applications. The link for the first, last, prev, or next page in the HTTP Link header should define it.
+        - endingBefore (string): A token used by the server to indicate the end of the page. Often this is a timestamp or an ID but it is not limited to those. This parameter should not be defined by client applications. The link for the first, last, prev, or next page in the HTTP Link header should define it.
+        - sortOrder (string): Sorted order of security events based on event detection time. Order options are 'ascending' or 'descending'. Default is ascending order.
+        """
+
+        kwargs.update(locals())
+
+        if 'sortOrder' in kwargs:
+            options = ['ascending', 'descending']
+            assert kwargs['sortOrder'] in options, f'''"sortOrder" cannot be "{kwargs['sortOrder']}", & must be set to one of: {options}'''
+
+        metadata = {
+            'tags': ['appliance', 'monitor', 'security', 'events'],
+            'operation': 'getOrganizationApplianceSecurityEvents',
+        }
+        resource = f'/organizations/{organizationId}/appliance/security/events'
+
+        query_params = ['t0', 't1', 'timespan', 'perPage', 'startingAfter', 'endingBefore', 'sortOrder']
+        params = {k: v for (k, v) in kwargs.items() if k in query_params}
+
+        return await self._session.get_pages(metadata, resource, params, total_pages, direction)
+
+
     async def getOrganizationApplianceSecurityIntrusion(self, organizationId: str):
         """
         **Returns all supported intrusion settings for an organization**
@@ -1224,3 +1333,80 @@ async def updateOrganizationApplianceSecurityIntrusion(self, organizationId: str
 
         return await self._session.put(metadata, resource, payload)
 
+    async def getOrganizationApplianceThirdPartyVPNPeers(self, organizationId: str):
+        """
+        **Return the third party VPN peers for an organization**
+        https://developer.cisco.com/docs/meraki-api-v1/#!get-organization-appliance-third-party-v-p-n-peers
+        
+        - organizationId (string)
+        """
+
+        metadata = {
+            'tags': ['appliance', 'configure', 'thirdPartyVPNPeers'],
+            'operation': 'getOrganizationApplianceThirdPartyVPNPeers',
+        }
+        resource = f'/organizations/{organizationId}/appliance/thirdPartyVPNPeers'
+
+        return await self._session.get(metadata, resource)
+
+    async def updateOrganizationApplianceThirdPartyVPNPeers(self, organizationId: str, peers: list):
+        """
+        **Update the third party VPN peers for an organization**
+        https://developer.cisco.com/docs/meraki-api-v1/#!update-organization-appliance-third-party-v-p-n-peers
+        
+        - organizationId (string)
+        - peers (array): The list of VPN peers
+        """
+
+        kwargs = locals()
+
+        metadata = {
+            'tags': ['appliance', 'configure', 'thirdPartyVPNPeers'],
+            'operation': 'updateOrganizationApplianceThirdPartyVPNPeers',
+        }
+        resource = f'/organizations/{organizationId}/appliance/thirdPartyVPNPeers'
+
+        body_params = ['peers']
+        payload = {k: v for (k, v) in kwargs.items() if k in body_params}
+
+        return await self._session.put(metadata, resource, payload)
+
+    async def getOrganizationApplianceVpnVpnFirewallRules(self, organizationId: str):
+        """
+        **Return the firewall rules for an organization's site-to-site VPN**
+        https://developer.cisco.com/docs/meraki-api-v1/#!get-organization-appliance-vpn-vpn-firewall-rules
+        
+        - organizationId (string)
+        """
+
+        metadata = {
+            'tags': ['appliance', 'configure', 'vpn', 'vpnFirewallRules'],
+            'operation': 'getOrganizationApplianceVpnVpnFirewallRules',
+        }
+        resource = f'/organizations/{organizationId}/appliance/vpn/vpnFirewallRules'
+
+        return await self._session.get(metadata, resource)
+
+    async def updateOrganizationApplianceVpnVpnFirewallRules(self, organizationId: str, **kwargs):
+        """
+        **Update the firewall rules of an organization's site-to-site VPN**
+        https://developer.cisco.com/docs/meraki-api-v1/#!update-organization-appliance-vpn-vpn-firewall-rules
+        
+        - organizationId (string)
+        - rules (array): An ordered array of the firewall rules (not including the default rule)
+        - syslogDefaultRule (boolean): Log the special default rule (boolean value - enable only if you've configured a syslog server) (optional)
+        """
+
+        kwargs.update(locals())
+
+        metadata = {
+            'tags': ['appliance', 'configure', 'vpn', 'vpnFirewallRules'],
+            'operation': 'updateOrganizationApplianceVpnVpnFirewallRules',
+        }
+        resource = f'/organizations/{organizationId}/appliance/vpn/vpnFirewallRules'
+
+        body_params = ['rules', 'syslogDefaultRule']
+        payload = {k: v for (k, v) in kwargs.items() if k in body_params}
+
+        return await self._session.put(metadata, resource, payload)
+