From ad2a5b77c89f9f5df3119638b74b7d4c409fbe97 Mon Sep 17 00:00:00 2001 From: maz Date: Mon, 13 Jan 2025 14:47:36 +0900 Subject: [PATCH] update README --- .../@aws-cdk/aws-location-alpha/README.md | 160 +++++++++--------- 1 file changed, 84 insertions(+), 76 deletions(-) diff --git a/packages/@aws-cdk/aws-location-alpha/README.md b/packages/@aws-cdk/aws-location-alpha/README.md index 0afe2c9e1c40e..5c76977208dfa 100644 --- a/packages/@aws-cdk/aws-location-alpha/README.md +++ b/packages/@aws-cdk/aws-location-alpha/README.md @@ -24,7 +24,88 @@ global, trusted providers Esri and HERE. With affordable data, tracking and geof capabilities, and built-in metrics for health monitoring, you can build sophisticated location-enabled applications. -## Map +## Geofence Collection + +Geofence collection resources allow you to store and manage geofences—virtual boundaries on a map. +You can evaluate locations against a geofence collection resource and get notifications when the location +update crosses the boundary of any of the geofences in the geofence collection. + +```ts +declare const key: kms.Key; + +new location.GeofenceCollection(this, 'GeofenceCollection', { + geofenceCollectionName: 'MyGeofenceCollection', // optional, defaults to a generated name + kmsKey: key, // optional, defaults to use an AWS managed key +}); +``` + +Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions +on the geofence collection: + +```ts +declare const role: iam.Role; + +const geofenceCollection = new location.GeofenceCollection(this, 'GeofenceCollection', { + geofenceCollectionName: 'MyGeofenceCollection', +}); + +geofenceCollection.grantRead(role); +``` + +## Tracker + +A tracker stores position updates for a collection of devices. The tracker can be used to query the devices' current location or location history. It stores the updates, but reduces storage space and visual noise by filtering the locations before storing them. + +For more information, see [Trackers](https://docs.aws.amazon.com/location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview). + +To create a tracker, define a `Tracker`: + +```ts +declare const key: kms.Key; + +new location.Tracker(this, 'Tracker', { + trackerName: 'MyTracker', // optional, defaults to a generated name + kmsKey: key, // optional, defaults to use an AWS managed key +}); +``` + +Use the `grant()`, `grantUpdateDevicePositions` or `grantRead()` method to grant the given identity permissions to perform actions +on the geofence collection: + +```ts +declare const role: iam.Role; + +const tracker = new location.Tracker(this, 'Tracker', { + trackerName: 'MyTracker', +}); + +tracker.grantRead(role); +``` + +If you want to associate a tracker with geofence collections, define a `geofenceCollections` property or use `addGeofenceCollections` method. + +```ts +declare const geofenceCollection: location.GeofenceCollection; +declare const geofenceCollectionForAdd: location.GeofenceCollection; +declare const tracker: location.Tracker; + +const tracker = new location.Tracker(this, 'Tracker', { + trackerName: 'MyTracker', + geofenceCollections: [geofenceCollection], +}); + +tracker.addGeofenceCollections(geofenceCollectionForAdd); +``` + +## Legacy Resources + +AWS has released new [Enhanced Places, Routes, and Maps](https://aws.amazon.com/about-aws/whats-new/2024/11/amazon-location-service-enhanced-places-routes-maps/?nc1=h_ls). Since these use AWS-managed resources, users no longer need to create Maps, Places, and Routes resources themselves. + +As a result, the following constructs are now considered legacy. + +For more information, see [developer guide](https://docs.aws.amazon.com/location/latest/developerguide/what-is.html). + +### Map The Amazon Location Service Map resource gives you access to the underlying basemap data for a map. You use the Map resource with a map rendering library to add an interactive map to your application. @@ -54,7 +135,7 @@ const map = new location.Map(this, 'Map', { map.grantRendering(role); ``` -## Place Index +### Place Index A key function of Amazon Location Service is the ability to search the geolocation information. Amazon Location provides this functionality via the Place index resource. The place index includes @@ -80,35 +161,7 @@ const placeIndex = new location.PlaceIndex(this, 'PlaceIndex'); placeIndex.grantSearch(role); ``` -## Geofence Collection - -Geofence collection resources allow you to store and manage geofences—virtual boundaries on a map. -You can evaluate locations against a geofence collection resource and get notifications when the location -update crosses the boundary of any of the geofences in the geofence collection. - -```ts -declare const key: kms.Key; - -new location.GeofenceCollection(this, 'GeofenceCollection', { - geofenceCollectionName: 'MyGeofenceCollection', // optional, defaults to a generated name - kmsKey: key, // optional, defaults to use an AWS managed key -}); -``` - -Use the `grant()` or `grantRead()` method to grant the given identity permissions to perform actions -on the geofence collection: - -```ts -declare const role: iam.Role; - -const geofenceCollection = new location.GeofenceCollection(this, 'GeofenceCollection', { - geofenceCollectionName: 'MyGeofenceCollection', -}); - -geofenceCollection.grantRead(role); -``` - -## Route Calculator +### Route Calculator Route calculator resources allow you to find routes and estimate travel time based on up-to-date road network and live traffic information from your chosen data provider. @@ -134,48 +187,3 @@ const routeCalculator = new location.RouteCalculator(this, 'RouteCalculator', { }); routeCalculator.grantRead(role); ``` - -## Tracker - -A tracker stores position updates for a collection of devices. The tracker can be used to query the devices' current location or location history. It stores the updates, but reduces storage space and visual noise by filtering the locations before storing them. - -For more information, see [Trackers](https://docs.aws.amazon.com/location/latest/developerguide/geofence-tracker-concepts.html#tracking-overview). - -To create a tracker, define a `Tracker`: - -```ts -declare const key: kms.Key; - -new location.Tracker(this, 'Tracker', { - trackerName: 'MyTracker', // optional, defaults to a generated name - kmsKey: key, // optional, defaults to use an AWS managed key -}); -``` - -Use the `grant()`, `grantUpdateDevicePositions` or `grantRead()` method to grant the given identity permissions to perform actions -on the geofence collection: - -```ts -declare const role: iam.Role; - -const tracker = new location.Tracker(this, 'Tracker', { - trackerName: 'MyTracker', -}); - -tracker.grantRead(role); -``` - -If you want to associate a tracker with geofence collections, define a `geofenceCollections` property or use `addGeofenceCollections` method. - -```ts -declare const geofenceCollection: location.GeofenceCollection; -declare const geofenceCollectionForAdd: location.GeofenceCollection; -declare const tracker: location.Tracker; - -const tracker = new location.Tracker(this, 'Tracker', { - trackerName: 'MyTracker', - geofenceCollections: [geofenceCollection], -}); - -tracker.addGeofenceCollections(geofenceCollectionForAdd); -```