AWS code-library documentation change
Summary
Added comprehensive Kotlin code example demonstrating AWS Location Service features including map creation, API key management, geofencing, device tracking, and route calculation
Security assessment
The change adds documentation about API key restrictions (geo:GetMap* actions and resource limitations) which is a security feature, but there's no evidence of addressing a specific security vulnerability
Diff
diff --git a/code-library/latest/ug/location_example_location_Scenario_section.md b/code-library/latest/ug/location_example_location_Scenario_section.md index afd8edf8e..327b2d5ac 100644 --- a//code-library/latest/ug/location_example_location_Scenario_section.md +++ b//code-library/latest/ug/location_example_location_Scenario_section.md @@ -9 +9 @@ There are more AWS SDK examples available in the [AWS Doc SDK Examples](https:// -The following code example shows how to: +The following code examples show how to: @@ -1054,0 +1055,669 @@ A wrapper class for Amazon Location Service SDK methods. +Kotlin + + +**SDK for Kotlin** + + +###### Note + +There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/location#code-examples). + + + /** + Before running this Kotlin code example, set up your development environment, + including your credentials. + + For more information, see the following documentation topic: + https://docs.aws.amazon.com/sdk-for-kotlin/latest/developer-guide/setup.html + */ + + val scanner = Scanner(System.`in`) + val DASHES = String(CharArray(80)).replace("\u0000", "-") + suspend fun main(args: Array<String>) { + val usage = """ + + Usage: <mapName> <keyName> <collectionName> <geoId> <trackerName> <calculatorName> <deviceId> + + Where: + mapName - The name of the map to create (e.g., "AWSMap"). + keyName - The name of the API key to create (e.g., "AWSApiKey"). + collectionName - The name of the geofence collection (e.g., "AWSLocationCollection"). + geoId - The geographic identifier used for the geofence or map (e.g., "geoId"). + trackerName - The name of the tracker (e.g., "geoTracker"). + calculatorName - The name of the route calculator (e.g., "AWSRouteCalc"). + deviceId - The ID of the device (e.g., "iPhone-112356"). + """ + + if (args.size != 7) { + println(usage) + exitProcess(0) + } + + val mapName = args[0] + val keyName = args[1] + val collectionName = args[2] + val geoId = args[3] + val trackerName = args[4] + val calculatorName = args[5] + val deviceId = args[6] + + println( + """ + AWS Location Service is a fully managed service offered by Amazon Web Services (AWS) that + provides location-based services for developers. This service simplifies + the integration of location-based features into applications, making it + easier to build and deploy location-aware applications. + + The AWS Location Service offers a range of location-based services, + including: + + - Maps: The service provides access to high-quality maps, satellite imagery, + and geospatial data from various providers, allowing developers to + easily embed maps into their applications. + + - Tracking: The Location Service enables real-time tracking of mobile devices, + assets, or other entities, allowing developers to build applications + that can monitor the location of people, vehicles, or other objects. + + - Geocoding: The service provides the ability to convert addresses or + location names into geographic coordinates (latitude and longitude), + and vice versa, enabling developers to integrate location-based search + and routing functionality into their applications. + """.trimIndent(), + ) + + waitForInputToContinue(scanner) + println(DASHES) + println("1. Create an AWS Location Service map") + println( + """ + An AWS Location map can enhance the user experience of your + application by providing accurate and personalized location-based + features. For example, you could use the geocoding capabilities to + allow users to search for and locate businesses, landmarks, or + other points of interest within a specific region. + + """.trimIndent(), + ) + + waitForInputToContinue(scanner) + val mapArn = createMap(mapName) + println("The Map ARN is: $mapArn") + waitForInputToContinue(scanner) + println(DASHES) + + waitForInputToContinue(scanner) + println("2. Create an AWS Location API key") + println( + """ + When you embed a map in a web app or website, the API key is + included in the map tile URL to authenticate requests. You can + restrict API keys to specific AWS Location operations (e.g., only + maps, not geocoding). API keys can expire, ensuring temporary + access control. + + """.trimIndent(), + ) + val keyArn = createKey(keyName, mapArn) + println("The Key ARN is: $keyArn") + waitForInputToContinue(scanner) + println(DASHES) + + println(DASHES) + println("3. Display Map URL") + println( + """ + In order to get the MAP URL, you need to get the API Key value. + You can get the key value using the AWS Management Console under + Location Services. This operation cannot be completed using the + AWS SDK. For more information about getting the key value, see + the AWS Location Documentation. + """.trimIndent(), + ) + val mapUrl = "https://maps.geo.aws.amazon.com/maps/v0/maps/$mapName/tiles/{z}/{x}/{y}?key={KeyValue}" + println("Embed this URL in your Web app: $mapUrl") + println("") + waitForInputToContinue(scanner) + println(DASHES) + + println(DASHES) + println("4. Create a geofence collection, which manages and stores geofences.") + waitForInputToContinue(scanner) + val collectionArn: String = + createGeofenceCollection(collectionName) + println("The geofence collection was successfully created: $collectionArn") + waitForInputToContinue(scanner) + + println(DASHES) + println("5. Store a geofence geometry in a given geofence collection.") + println( + """ + An AWS Location geofence is a virtual boundary that defines a geographic area + on a map. It is a useful feature for tracking the location of + assets or monitoring the movement of objects within a specific region. + + To define a geofence, you need to specify the coordinates of a + polygon that represents the area of interest. The polygon must be + defined in a counter-clockwise direction, meaning that the points of + the polygon must be listed in a counter-clockwise order. + + This is a requirement for the AWS Location service to correctly + interpret the geofence and ensure that the location data is + accurately processed within the defined area. + """.trimIndent(), + ) + + waitForInputToContinue(scanner) + putGeofence(collectionName, geoId) + println("Successfully created geofence: $geoId") + waitForInputToContinue(scanner) + println(DASHES) + + println(DASHES) + println("6. Create a tracker resource which lets you retrieve current and historical location of devices.") + waitForInputToContinue(scanner) + val trackerArn: String = createTracker(trackerName) + println("Successfully created tracker. ARN: $trackerArn") + waitForInputToContinue(scanner) + println(DASHES) + + println(DASHES) + println("7. Update the position of a device in the location tracking system.") + println( + """ + The AWS location service does not enforce a strict format for deviceId, but it must: + - Be a string (case-sensitive). + - Be 1–100 characters long. + - Contain only: + - Alphanumeric characters (A-Z, a-z, 0-9) + - Underscores (_) + - Hyphens (-) + - Be the same ID used when sending and retrieving positions. + + """.trimIndent(), + ) + + waitForInputToContinue(scanner) + updateDevicePosition(trackerName, deviceId) + println("$deviceId was successfully updated in the location tracking system.") + waitForInputToContinue(scanner) + println(DASHES) + + println(DASHES)