Update README.md to enhance Azure Maps sample documentation with detailed authentication methods and scenarios

Author: anotherRedbeard

samples/azure-maps/README.md

@@ -1,34 +1,52 @@
-# Samples: Api Management proxing calls to Azure Maps
+# Samples: Api Management proxying calls to Azure Maps
 
-This is a sample demonstrating how to use Azure API Management (APIM) to proxy calls to the Azure Maps service. This setup allows you to manage, secure, and monitor access to Azure Maps through APIM.
+This sample demonstrates how to use Azure API Management (APIM) to proxy calls to Azure Maps service using **three different authentication methods**. This setup allows you to manage, secure, and monitor access to Azure Maps through APIM while showcasing various authentication patterns for different use cases.
 
 ⚙️ **Supported infrastructures**: All infrastructures
 
-👟 **Expected *Run All* runtime (excl. infrastructure prerequisite): ~[NOTEBOOK RUNTIME] minute**
+👟 **Expected *Run All* runtime (excl. infrastructure prerequisite): ~2 minutes**
 
 ## 🎯 Objectives
 
-1. Learn how to set up APIM to proxy requests to Azure Maps on a path to operation based mapping.
-1. Learn how to set up APIM to proxy requests to Azure Maps on a generic path.
-1. See how to secure access to Azure Maps using APIM policies for all 3 authentication methods (subscription key, Azure Entra AD, and SAS Tokens).
-1. Show how to connect to the v1 enpoint of Azure Maps using APIM.
+1. **Demonstrate three Azure Maps authentication patterns:**
+   - **Shared Key Authentication** - Using Azure Maps subscription keys
+   - **Azure Entra ID (Managed Identity)** - Recommended approach for production scenarios
+   - **SAS Token Authentication** - Dynamic token generation with fine-grained control
+2. Learn path-to-operation mapping vs. generic proxy patterns in APIM
+3. Understand how APIM can enable chargeback/cost allocation scenarios for Azure Maps usage
+4. Show integration with both v1 and v2 Azure Maps API endpoints
 
 ## 📝 Scenario
 
-This sample demonstrates how to use APIM to proxy requests to the Azure Maps service. By doing so, you can leverage APIM's capabilities to manage, secure, and monitor access to Azure Maps. This particular setup will show you how to map specific paths to Azure Maps APIs, as well as how to handle generic paths. Additionally, the sample will illustrate how to secure access to Azure Maps using different authentication methods supported by APIM policies.
+Organizations migrating from services like Bing Maps to Azure Maps often need flexible authentication and billing models. This sample addresses common questions about:
+
+- **Authentication flexibility**: While Azure Entra ID with Managed Identity is the recommended production approach, some scenarios require shared keys or SAS tokens
+- **Cost allocation**: Using APIM subscription keys to enable chargeback models and usage tracking per department/application
+- **Migration patterns**: Supporting different authentication methods during transition periods
+- **API management**: Centralizing access control, rate limiting, and monitoring for Azure Maps
+
+### Authentication Scenarios Demonstrated:
+
+1. **🔑 Shared Key (Subscription Key)**: Direct use of Azure Maps primary/secondary keys - simpler but less granular control
+2. **🛡️ Azure Entra ID (Managed Identity)**: Recommended for production - leverages Azure RBAC and eliminates key management
+3. **🎫 SAS Token**: Dynamic token generation with configurable expiration, rate limits, and regional restrictions - ideal for fine-grained access control
+
+> **Note**: In production scenarios, SAS token generation would typically be handled by a separate Azure Function or API service. This sample demonstrates in-policy generation for simplicity and educational purposes.
 
 ## 🛩️ Lab Components
 
 This lab sets up:
 
-- An Azure Maps resource in Azure
-- 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
+- **Azure Maps Account** with Gen2 pricing tier
+- **APIM Managed Identity** with roles:
+  - **Azure Maps Data Reader**: Read access to Maps APIs
+  - **Azure Maps Contributor**: Ability to generate SAS tokens
+- **User Assigned Managed Identity (UAMI)** for SAS token principal, with:
+  - **Azure Maps Data Reader**: Used as the identity for SAS token operations
+- **Three API Operations** demonstrating each authentication method:
+  - `/geocode` - Azure Entra ID authentication
+  - `/geocode/batch/async` - Shared key authentication  
+  - `/default/*` - SAS token authentication with caching
 
 ## ⚙️ Configuration