AWS code-library documentation change
Summary
Added JavaScript code example demonstrating AWS Location Service operations including map creation, geofencing, device tracking, route calculation, and resource cleanup
Security assessment
The change adds documentation about API key usage patterns and security best practices (restricting API keys to specific operations, key expiration). While it mentions security features, there's no evidence of addressing a specific vulnerability or security incident.
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 327b2d5ac..29a181d43 100644 --- a//code-library/latest/ug/location_example_location_Scenario_section.md +++ b//code-library/latest/ug/location_example_location_Scenario_section.md @@ -1054,0 +1055,632 @@ A wrapper class for Amazon Location Service SDK methods. +JavaScript + + +**SDK for JavaScript (v3)** + + +###### 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/javascriptv3/example_code/location/scenarios#code-examples). + + + /* + Before running this JavaScript code example, set up your development environment, including your credentials. + This demo illustrates how to use the AWS SDK for JavaScript (v3) to work with Amazon Location Service. + + For more information, see the following documentation topic: + + https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html + */ + + import { + Scenario, + ScenarioAction, + ScenarioInput, + ScenarioOutput, + } from "@aws-doc-sdk-examples/lib/scenario/index.js"; + + import { + CreateMapCommand, + CreateGeofenceCollectionCommand, + PutGeofenceCommand, + CreateTrackerCommand, + BatchUpdateDevicePositionCommand, + GetDevicePositionCommand, + CreateRouteCalculatorCommand, + CalculateRouteCommand, + LocationClient, + ConflictException, + ResourceNotFoundException, + DeleteGeofenceCollectionCommand, + DeleteRouteCalculatorCommand, + DeleteTrackerCommand, + DeleteMapCommand, + } from "@aws-sdk/client-location"; + + import { + GeoPlacesClient, + ReverseGeocodeCommand, + SearchNearbyCommand, + SearchTextCommand, + GetPlaceCommand, + ValidationException, + } from "@aws-sdk/client-geo-places"; + + import { parseArgs } from "node:util"; + import { fileURLToPath } from "node:url"; + + /*The inputs for this example can be edited in the ./input.json.*/ + import data from "./inputs.json" with { type: "json" }; + + /** + * Used repeatedly to have the user press enter. + * @type {ScenarioInput} + */ + /* v8 ignore next 3 */ + const pressEnter = new ScenarioInput("continue", "Press Enter to continue", { + type: "confirm", + verbose: "false", + }); + + const pressEnterConfirm = new ScenarioInput( + "confirm", + "Press Enter to continue", + { + type: "confirm", + verbose: "false", + }, + ); + + const region = "eu-west-1"; + + const locationClient = new LocationClient({ region: region }); + + const greet = new ScenarioOutput( + "greet", + "Welcome to the Amazon Location Use demo! \n" + + "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 " + + "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:\n" + + "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.\n" + + "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. " + + "Please define values ./inputs.json for each user-defined variable used in this app. Otherwise the default is used:\n" + + "- mapName: The name of the map to be create (default is 'AWSMap').\n" + + "- keyName: The name of the API key to create (default is ' AWSApiKey')\n" + + "- collectionName: The name of the geofence collection (default is 'AWSLocationCollection')\n" + + "- geoId: The geographic identifier used for the geofence or map (default is 'geoId')\n" + + "- trackerName: The name of the tracker (default is 'geoTracker')\n" + + "- calculatorName: The name of the route calculator (default is 'AWSRouteCalc')\n" + + "- deviceId: The ID of the device (default is 'iPhone-112356')", + + { header: true }, + ); + const displayCreateAMap = new ScenarioOutput( + "displayCreateAMap", + "1. Create a map\n" + + "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.", + ); + + const sdkCreateAMap = new ScenarioAction( + "sdkCreateAMap", + async (/** @type {State} */ state) => { + const createMapParams = { + MapName: `${data.inputs.mapName}`, + Configuration: { style: "VectorEsriNavigation" }, + }; + try { + const command = new CreateMapCommand(createMapParams); + const response = await locationClient.send(command); + state.MapName = response.MapName; + console.log("Map created. Map ARN is: ", state.MapName); + } catch (error) { + console.error("Error creating map: ", error); + throw error; + } + }, + ); + + const displayMapUrl = new ScenarioOutput( + "displayMapUrl", + "2. Display Map URL\n" + + "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.\n" + + "In order to get the MAP URL you need to create and get the API Key value. " + + "You can create and get the key value using the AWS Management Console under " + + "Location Services. These operations cannot be completed using the " + + "AWS SDK. For more information about getting the key value, see " + + "the AWS Location Documentation.", + ); + + const sdkDisplayMapUrl = new ScenarioAction( + "sdkDisplayMapUrl", + async (/** @type {State} */ state) => { + const mapURL = `https://maps.geo.aws.amazon.com/maps/v0/maps/${state.MapName}/tiles/{z}/{x}/{y}?key=API_KEY_VALUE`; + state.mapURL = mapURL; + console.log( + `Replace \'API_KEY_VALUE\' in the following URL with the value for the API key you create and get from the AWS Management Console under Location Services. This is then the Map URL you can embed this URL in your Web app:\n + ${state.mapURL}`, + ); + }, + ); + const displayCreateGeoFenceColl = new ScenarioOutput( + "displayCreateGeoFenceColl", + "3. Create a geofence collection, which manages and stores geofences.", + ); + + const sdkCreateGeoFenceColl = new ScenarioAction( + "sdkCreateGeoFenceColl", + async (/** @type {State} */ state) => { + // Creates a new geofence collection. + const geoFenceCollParams = { + CollectionName: `${data.inputs.collectionName}`, + }; + try { + const command = new CreateGeofenceCollectionCommand(geoFenceCollParams); + const response = await locationClient.send(command); + state.CollectionName = response.CollectionName; + console.log( + `The geofence collection was successfully created: ${state.CollectionName}`, + ); + } catch (caught) { + if (caught instanceof ConflictException) { + console.error( + `An unexpected error occurred while creating the geofence collection: ${caught.message} \n Exiting program.`, + ); + return; + } + } + }, + ); + const displayStoreGeometry = new ScenarioOutput(