Update Azure Maps sample documentation and enhance async request handling in ApimRequests

Author: anotherRedbeard

README.md

@@ -146,6 +146,7 @@ For detailed troubleshooting of setup issues, see [Import Troubleshooting Guide]
 | [General](./samples/general/README.md)                          | Basic demo of APIM sample setup and policy usage.                                                                   | All infrastructures           |
 | [Load Balancing](./samples/load-balancing/README.md)            | Priority and weighted load balancing across backends.                                                               | apim-aca, afd-apim (with ACA) |
 | [Secure Blob Access](./samples/secure-blob-access/README.md)    | Secure blob access via the [valet key pattern](https://learn.microsoft.com/azure/architecture/patterns/valet-key).  | All infrastructures           |
+| [Azure Maps](./samples/azure-maps/README.md)                    | Proxying calls to Azure Maps with APIM policies.                                                                    | All infrastructures           |
 
 ### ▶️ Running a Sample
 

samples/azure-maps/README.md

@@ -22,7 +22,11 @@ This sample demonstrates how to use APIM to proxy requests to the Azure Maps ser
 This lab sets up:
 
 - An Azure Maps resource in Azure
-- APIM managed identity with Storage Blob Data Reader permissions
+- APIM managed identity with the following roles:
+  - **Azure Maps Search and Render Data Reader:** Grants the ability to call the apis and render the maps
+  - **Azure Maps Contributor:** Grants the ability to create the SAS Token from the APIM policy
+- A User Assigned Managed Identity (UAMI) that is used as the principal id to emulate when creating the SAS Token for Azure Maps. It has the following roles asigned:
+  - **Azure Maps Search and Render Data Reader:** Grants the ability to call the apis and render the maps
 - An API that demonstrates proxying requests to Azure Maps specific to APIs (geocode, search, etc.)
   - Also in that api there will be an operation that demonstrates a generic path to Azure Maps
 

samples/azure-maps/create.ipynb

@@ -8,8 +8,6 @@
     "\n",
     "Configures everything that's needed for deployment. \n",
     "\n",
-    "[ADD ANY SPECIAL INSTRUCTIONS]\n",
-    "\n",
     "**Modify entries under _1) User-defined parameters_ and _3) Define the APIs and their operations and policies_**."
    ]
   },
@@ -49,14 +47,11 @@
     "mapApi_v2_geocode_get = GET_APIOperation2('get-geocode','Get Geocode','/geocode','Get geocode endpoint',map_geocode_v2_aad_get_xml)\n",
     "api1 = API('map-api', 'Map API', '/map', 'This is the proxy for Azure Maps', operations=[mapApi_v2_default_get, mapApi_v1_async_post,mapApi_v2_geocode_get], tags = tags, serviceUrl=azure_maps_url)\n",
     "\n",
-    "# API n\n",
-    "# ...\n",
-    "\n",
     "# APIs Array\n",
     "# apis: List[API] = [api1, apin]\n",
     "apis: List[API] = [api1]\n",
     "\n",
-    "# 4) Set up the named values\n",
+    "# 4) Set up the named values, for this specific sample, we are using some of the named values in the API policies defined above that can't be known at this point in the process. For those named values, we are setting them in the main.bicep file.\n",
     "nvs: List[NamedValue] = [\n",
     "    NamedValue('azure-maps-arm-api-version','2023-06-01')\n",
     "]\n",
@@ -125,35 +120,23 @@
     "import utils\n",
     "from apimrequests import ApimRequests\n",
     "\n",
-    "# [ADD RELEVANT TESTS HERE]\n",
+    "reqs = ApimRequests(apim_gateway_url)\n",
     "\n",
     "# 1) Issue a direct request to API Management\n",
-    "# reqsApim = ApimRequests(apim_gateway_url)\n",
-    "# reqsApim.singleGet('/request-headers', msg = 'Calling Request Headers API via API Management Gateway URL. Response codes 200 and 403 are both valid depending on the infrastructure used.')\n",
-    "\n",
-    "# # 2) Issue requests against Front Door.\n",
-    "# # Check if the infrastructure architecture deployment uses Azure Front Door.\n",
-    "# utils.print_message('Checking if the infrastructure architecture deployment uses Azure Front Door.', blank_above = True)\n",
-    "# afd_endpoint_url = utils.get_frontdoor_url(deployment, rg_name)\n",
-    "\n",
-    "# if afd_endpoint_url:\n",
-    "#     reqsAfd = ApimRequests(afd_endpoint_url)\n",
-    "#     reqsAfd.singleGet('/request-headers', msg = 'Calling Request Headers API via via Azure Front Door. Expect 200.')\n",
-    "\n",
-    "reqs = ApimRequests(apim_gateway_url)\n",
+    "reqs.singleGet('/', msg = 'Calling Hello World (Root) API. Expect 200.')\n",
     "\n",
-    "reqs.singleGet('/', msg = 'Calling Hello World (Root) API')\n",
-    "reqs.singleGet('/map/default/geocode?query=15127%20NE%2024th%20Street%20Redmond%20WA', msg = 'Calling Default Route API with AAD Auth')\n",
-    "reqs.singleGet('/map/geocode?query=15127%20NE%2024th%20Street%20Redmond%20WA', msg = 'Calling Geocode v2 API with AAD Auth')\n",
-    "reqs.singlePost('/map/geocode/batch/async', data={\n",
+    "# 2) Issue requests to API Management with Azure Maps APIs\n",
+    "reqs.singleGet('/map/default/geocode?query=15127%20NE%2024th%20Street%20Redmond%20WA', msg = 'Calling Default Route API with AAD Auth. Expect 200.')\n",
+    "reqs.singleGet('/map/geocode?query=15127%20NE%2024th%20Street%20Redmond%20WA', msg = 'Calling Geocode v2 API with AAD Auth. Expect 200.')\n",
+    "reqs.singlePostAsync('/map/geocode/batch/async', data={\n",
     "    \"batchItems\": [\n",
     "        {\"query\": \"?query=400 Broad St, Seattle, WA 98109&limit=3\"},\n",
     "        {\"query\": \"?query=One, Microsoft Way, Redmond, WA 98052&limit=3\"},\n",
     "        {\"query\": \"?query=350 5th Ave, New York, NY 10118&limit=1\"},\n",
     "        {\"query\": \"?query=Pike Pl, Seattle, WA 98101&lat=47.610970&lon=-122.342469&radius=1000\"},\n",
     "        {\"query\": \"?query=Champ de Mars, 5 Avenue Anatole France, 75007 Paris, France&limit=1\"}\n",
     "    ]\n",
-    "}, msg = 'Calling Async Geocode Batch v1 API with Key Auth')\n",
+    "}, msg = 'Calling Async Geocode Batch v1 API with Key Auth. Expect 200', timeout=120, poll_interval=3)\n",
     "\n",
     "utils.print_ok('All done!')"
    ]

samples/azure-maps/main.bicep

@@ -147,6 +147,14 @@ module apisModule '../../shared/bicep/modules/apim/v1/api.bicep' = [for api in a
     appInsightsId: appInsightsId
     api: api
   }
+  dependsOn: [
+    mapsSubscriptionKeyNamedValue
+    mapsClientIdNamedValue
+    userAssignedIdentityObjectIdNamedValue
+    subscriptionIdNamedValue
+    resourceGroupNamedValue
+    azureMapsResourceNamedValue
+  ]
 }]
 
 // Grant APIM managed identity access to Azure Maps, here are the RBAC roles you might need: https://learn.microsoft.com/en-us/azure/azure-maps/azure-maps-authentication#picking-a-role-definition

shared/python/apimrequests.py

@@ -212,6 +212,43 @@ def _print_response_code(self, response) -> None:
 
         utils.print_val("Response status", status_code_str)
 
+    def _poll_async_operation(self, location_url: str, headers: dict = None, timeout: int = 60, poll_interval: int = 2) -> requests.Response | None:
+        """
+        Poll an async operation until completion.
+        
+        Args:
+            location_url: The URL from the Location header
+            headers: Headers to include in polling requests
+            timeout: Maximum time to wait in seconds
+            poll_interval: Time between polls in seconds
+            
+        Returns:
+            The final response when operation completes or None on error
+        """
+        start_time = time.time()
+        
+        while time.time() - start_time < timeout:
+            try:
+                response = requests.get(location_url, headers=headers or {})
+                
+                utils.print_info(f"Polling operation - Status: {response.status_code}")
+                
+                if response.status_code == 200:
+                    utils.print_ok("Async operation completed successfully!")
+                    return response
+                elif response.status_code == 202:
+                    utils.print_info(f"Operation still in progress, waiting {poll_interval} seconds...")
+                    time.sleep(poll_interval)
+                else:
+                    utils.print_error(f"Unexpected status code during polling: {response.status_code}")
+                    return response
+                    
+            except requests.exceptions.RequestException as e:
+                utils.print_error(f"Error polling operation: {e}")
+                return None
+        
+        utils.print_error(f"Async operation timeout reached after {timeout} seconds")
+        return None
 
     # ------------------------------
     #    PUBLIC METHODS
@@ -264,4 +301,93 @@ def multiGet(self, path: str, runs: int, headers = None, data = None, msg: str |
             List of response dicts for each run.
         """
 
-        return self._multiRequest(method = HTTP_VERB.GET, path = path, runs = runs, headers = headers, data = data, msg = msg, printResponse = printResponse, sleepMs = sleepMs)
+        return self._multiRequest(method = HTTP_VERB.GET, path = path, runs = runs, headers = headers, data = data, msg = msg, printResponse = printResponse, sleepMs = sleepMs)
+    
+    def singlePostAsync(self, path: str, *, headers = None, data = None, msg: str | None = None, printResponse = True, timeout = 60, poll_interval = 2) -> Any:
+        """
+        Make an async POST request to the Azure API Management service and poll until completion.
+    
+        Args:
+            path: The path to append to the base URL for the request.
+            headers: Additional headers to include in the request.
+            data: Data to include in the request body.
+            msg: Optional message to display.
+            printResponse: Whether to print the returned output.
+            timeout: Maximum time to wait for completion in seconds.
+            poll_interval: Time between polls in seconds.
+    
+        Returns:
+            str | None: The JSON response as a string, or None on error.
+        """
+    
+        try:
+            if msg:
+                utils.print_message(msg, blank_above = True)
+    
+            url = self.url + path
+            utils.print_info(f"POST {url}")
+    
+            merged_headers = self.headers.copy()
+    
+            if headers:
+                merged_headers.update(headers)
+    
+            # Make the initial async request
+            response = requests.request(HTTP_VERB.POST.value, url, headers = merged_headers, json = data)
+            
+            utils.print_info(f"Initial response status: {response.status_code}")
+            
+            if response.status_code == 202:  # Accepted - async operation started
+                location_header = response.headers.get('Location')
+                if location_header:
+                    utils.print_info(f"Found Location header: {location_header}")
+                    
+                    # Poll the location URL until completion
+                    final_response = self._poll_async_operation(
+                        location_header, 
+                        headers=merged_headers,
+                        timeout=timeout,
+                        poll_interval=poll_interval
+                    )
+                    
+                    if final_response and final_response.status_code == 200:
+                        if printResponse:
+                            self._print_response(final_response)
+                        
+                        content_type = final_response.headers.get('Content-Type')
+                        responseBody = None
+    
+                        if content_type and 'application/json' in content_type:
+                            responseBody = json.dumps(final_response.json(), indent = 4)
+                        else:
+                            responseBody = final_response.text
+    
+                        return responseBody
+                    else:
+                        utils.print_error("Async operation failed or timed out")
+                        return None
+                else:
+                    utils.print_error("No Location header found in 202 response")
+                    if printResponse:
+                        self._print_response(response)
+                    return None
+            else:
+                # Non-async response, handle normally
+                if printResponse:
+                    self._print_response(response)
+                
+                content_type = response.headers.get('Content-Type')
+                responseBody = None
+    
+                if content_type and 'application/json' in content_type:
+                    responseBody = json.dumps(response.json(), indent = 4)
+                else:
+                    responseBody = response.text
+    
+                return responseBody
+    
+        except requests.exceptions.RequestException as e:
+            utils.print_error(f"Error making request: {e}")
+            return None
+    
+