@azure-rest/maps-route 1.0.0-beta.3 → 1.0.0-beta.5

package/LICENSE

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+Copyright (c) Microsoft Corporation.
 
-Copyright (c) 2022 Microsoft
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -12,10 +12,10 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -9,7 +9,7 @@ Key links:
 - [Source code][source_code]
 - [Package (NPM)][npm_link]
 - [API reference documentation][api_ref]
-- [Product Information](https://docs.microsoft.com/rest/api/maps/route)
+- [Product Information](https://learn.microsoft.com/rest/api/maps/route)
 
 ## Getting started
 
@@ -21,9 +21,9 @@ Key links:
 ### Prerequisites
 
 - An [Azure subscription][azure_sub].
-- An [Azure Maps account](https://docs.microsoft.com/azure/azure-maps/how-to-manage-account-keys). You can create the resource via the [Azure Portal][azure_portal], the [Azure PowerShell][azure_powershell], or the [Azure CLI][azure_cli].
+- An [Azure Maps account](https://learn.microsoft.com/azure/azure-maps/how-to-manage-account-keys). You can create the resource via the [Azure Portal][azure_portal], the [Azure PowerShell][azure_powershell], or the [Azure CLI][azure_cli].
 
-If you use Azure CLI, replace `<resource-group-name>` and `<map-account-name>` of your choice, and select a proper [pricing tier](https://docs.microsoft.com/azure/azure-maps/choose-pricing-tier) based on your needs via the `<sku-name>` parameter. Please refer to [this page](https://docs.microsoft.com/cli/azure/maps/account?view=azure-cli-latest#az_maps_account_create) for more details.
+If you use Azure CLI, replace `<resource-group-name>` and `<map-account-name>` of your choice, and select a proper [pricing tier](https://learn.microsoft.com/azure/azure-maps/choose-pricing-tier) based on your needs via the `<sku-name>` parameter. Please refer to [this page](https://learn.microsoft.com/cli/azure/maps/account?view=azure-cli-latest#az_maps_account_create) for more details.
 
 ### Install the `@azure-rest/maps-route` package
 
@@ -35,26 +35,26 @@ npm install @azure-rest/maps-route
 
 ### Create and authenticate a `MapsRouteClient`
 
-To create a client object to access the Azure Maps Route APIs, you will need a `credential` object. The Azure Maps Route client can use an Azure Active Directory credential or an Azure Key credential to authenticate.
+To create a client object to access the Azure Maps Route APIs, you will need a `credential` object. The Azure Maps Route client can use a Microsoft Entra ID credential or an Azure Key credential to authenticate.
 
-#### Using an Azure Active Directory Credential
+#### Using a Microsoft Entra ID Credential
 
-You can authenticate with Azure Active Directory using the [Azure Identity library][azure_identity]. To use the [DefaultAzureCredential][defaultazurecredential] provider shown below, or other credential providers provided with the Azure SDK, please install the `@azure/identity` package:
+You can authenticate with Microsoft Entra ID using the [Azure Identity library][azure_identity]. To use the [DefaultAzureCredential][defaultazurecredential] provider shown below, or other credential providers provided with the Azure SDK, please install the `@azure/identity` package:
 
 ```bash
 npm install @azure/identity
 ```
 
-You will also need to register a new AAD application and grant access to Azure Maps by assigning the suitable role to your service principal. Please refer to the [Manage authentication](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication) page.
+You will also need to register a new Microsoft Entra ID application and grant access to Azure Maps by assigning the suitable role to your service principal. Please refer to the [Manage authentication](https://learn.microsoft.com/azure/azure-maps/how-to-manage-authentication) page.
 
-Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`.
+Set the values of the client ID, tenant ID, and client secret of the Microsoft Entra ID application as environment variables: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`.
 
 You will also need to specify the Azure Maps resource you intend to use by specifying the `clientId` in the client options.
-The Azure Maps resource client id can be found in the Authentication sections in the Azure Maps resource. Please refer to the [documentation](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication#view-authentication-details) on how to find it.
+The Azure Maps resource client id can be found in the Authentication sections in the Azure Maps resource. Please refer to the [documentation](https://learn.microsoft.com/azure/azure-maps/how-to-manage-authentication#view-authentication-details) on how to find it.
 
-```javascript
-const MapsRoute = require("@azure-rest/maps-route").default;
-const { DefaultAzureCredential } = require("@azure/identity");
+```ts snippet:ReadmeSampleCreateClient_TokenCredential
+import { DefaultAzureCredential } from "@azure/identity";
+import MapsRoute from "@azure-rest/maps-route";
 
 const credential = new DefaultAzureCredential();
 const client = MapsRoute(credential, "<maps-account-client-id>");
@@ -64,9 +64,9 @@ const client = MapsRoute(credential, "<maps-account-client-id>");
 
 You can authenticate with your Azure Maps Subscription Key.
 
-```javascript
-const MapsRoute = require("@azure-rest/maps-route").default;
-const { AzureKeyCredential } = require("@azure/core-auth");
+```ts snippet:ReadmeSampleCreateClient_SubscriptionKey
+import { AzureKeyCredential } from "@azure/core-auth";
+import MapsRoute from "@azure-rest/maps-route";
 
 const credential = new AzureKeyCredential("<subscription-key>");
 const client = MapsRoute(credential);
@@ -88,34 +88,37 @@ npm install @azure/core-auth
 
 Finally, you can use the SAS token to authenticate the client:
 
-```javascript
-  const MapsRoute = require("@azure-rest/maps-route").default;
-  const { AzureSASCredential } = require("@azure/core-auth");
-  const { DefaultAzureCredential } = require("@azure/identity");
-  const { AzureMapsManagementClient } = require("@azure/arm-maps");
-
-  const subscriptionId = "<subscription ID of the map account>"
-  const resourceGroupName = "<resource group name of the map account>";
-  const accountName = "<name of the map account>";
-  const mapsAccountSasParameters = {
-    start: "<start time in ISO format>", // e.g. "2023-11-24T03:51:53.161Z"
-    expiry: "<expiry time in ISO format>", // maximum value to start + 1 day
-    maxRatePerSecond: 500,
-    principalId: "<principle ID (object ID) of the managed identity>",
-    signingKey: "primaryKey",
-  };
-  const credential = new DefaultAzureCredential();
-  const managementClient = new AzureMapsManagementClient(credential, subscriptionId);
-  const {accountSasToken} = await managementClient.accounts.listSas(
-    resourceGroupName,
-    accountName,
-    mapsAccountSasParameters
-  );
-  if (accountSasToken === undefined) {
-    throw new Error("No accountSasToken was found for the Maps Account.");
-  }
-  const sasCredential = new AzureSASCredential(accountSasToken);
-  const client = MapsRoute(sasCredential);
+```ts snippet:ReadmeSampleCreateClient_SAS
+import { DefaultAzureCredential } from "@azure/identity";
+import { AzureMapsManagementClient } from "@azure/arm-maps";
+import { AzureSASCredential } from "@azure/core-auth";
+import MapsRoute from "@azure-rest/maps-route";
+
+const subscriptionId = "<subscription ID of the map account>";
+const resourceGroupName = "<resource group name of the map account>";
+const accountName = "<name of the map account>";
+const mapsAccountSasParameters = {
+  start: "<start time in ISO format>", // e.g. "2023-11-24T03:51:53.161Z"
+  expiry: "<expiry time in ISO format>", // maximum value to start + 1 day
+  maxRatePerSecond: 500,
+  principalId: "<principle ID (object ID) of the managed identity>",
+  signingKey: "primaryKey",
+};
+
+const credential = new DefaultAzureCredential();
+const managementClient = new AzureMapsManagementClient(credential, subscriptionId);
+const { accountSasToken } = await managementClient.accounts.listSas(
+  resourceGroupName,
+  accountName,
+  mapsAccountSasParameters,
+);
+
+if (accountSasToken === undefined) {
+  throw new Error("No accountSasToken was found for the Maps Account.");
+}
+
+const sasCredential = new AzureSASCredential(accountSasToken);
+const client = MapsRoute(sasCredential);
 ```
 
 ## Examples
@@ -134,8 +137,13 @@ To retrieve the route direction, you need to pass in the parameters the coordina
 
 By default, the Route service will return an array of coordinates. The response will contain the coordinates that make up the path in a list named points. Route response also includes the distance from the start of the route and the estimated elapsed time. These values can be used to calculate the average speed for the entire route.
 
-```javascript
-const { toColonDelimitedLatLonString, isUnexpected } = require("@azure-rest/maps-route");
+```ts snippet:ReadmeSampleRouteDirections
+import { DefaultAzureCredential } from "@azure/identity";
+import MapsRoute, { toColonDelimitedLatLonString, isUnexpected } from "@azure-rest/maps-route";
+
+const credential = new DefaultAzureCredential();
+const client = MapsRoute(credential, "<maps-account-client-id>");
+
 const routeDirectionsResult1 = await client.path("/route/directions/{format}", "json").get({
   queryParameters: {
     query: "51.368752,-0.118332:41.385426,-0.128929",
@@ -165,13 +173,11 @@ if (isUnexpected(routeDirectionsResult2)) {
 
 routeDirectionsResult2.body.routes.forEach(({ summary, legs }) => {
   console.log(
-    `The total distance is ${summary.lengthInMeters} meters, and it takes ${summary.travelTimeInSeconds} seconds.`
+    `The total distance is ${summary.lengthInMeters} meters, and it takes ${summary.travelTimeInSeconds} seconds.`,
   );
   legs.forEach(({ summary, points }, idx) => {
     console.log(
-      `The ${idx + 1}th leg's length is ${summary.lengthInMeters} meters, and it takes ${
-        summary.travelTimeInSeconds
-      } seconds. Followings are the first 10 points: `
+      `The ${idx + 1}th leg's length is ${summary.lengthInMeters} meters, and it takes ${summary.travelTimeInSeconds} seconds. Followings are the first 10 points: `,
     );
     console.table(points.slice(0, 10));
   });
@@ -182,8 +188,13 @@ routeDirectionsResult2.body.routes.forEach(({ summary, legs }) => {
 
 The service supports commercial vehicle routing, covering commercial trucks routing. The APIs consider specified limits. Such as, the height and weight of the vehicle, and if the vehicle is carrying hazardous cargo. For example, if a vehicle is carrying flammable, the routing engine avoid certain tunnels that are near residential areas.
 
-```javascript
-const { toColonDelimitedLatLonString, isUnexpected } = require("@azure-rest/maps-route");
+```ts snippet:ReadmeSampleRouteDirectionsCommercialVehicle
+import { DefaultAzureCredential } from "@azure/identity";
+import MapsRoute, { toColonDelimitedLatLonString, isUnexpected } from "@azure-rest/maps-route";
+
+const credential = new DefaultAzureCredential();
+const client = MapsRoute(credential, "<maps-account-client-id>");
+
 const routeDirectionsResult = await client.path("/route/directions/{format}", "json").get({
   queryParameters: {
     query: toColonDelimitedLatLonString([
@@ -210,13 +221,11 @@ if (isUnexpected(routeDirectionsResult)) {
 
 routeDirectionsResult.body.routes.forEach(({ summary, legs }) => {
   console.log(
-    `The total distance is ${summary.lengthInMeters} meters, and it takes ${summary.travelTimeInSeconds} seconds.`
+    `The total distance is ${summary.lengthInMeters} meters, and it takes ${summary.travelTimeInSeconds} seconds.`,
   );
   legs.forEach(({ summary, points }, idx) => {
     console.log(
-      `The ${idx + 1}th leg's length is ${summary.lengthInMeters} meters, and it takes ${
-        summary.travelTimeInSeconds
-      } seconds. Followings are the first 10 points: `
+      `The ${idx + 1}th leg's length is ${summary.lengthInMeters} meters, and it takes ${summary.travelTimeInSeconds} seconds. Followings are the first 10 points: `,
     );
     console.table(points.slice(0, 10));
   });
@@ -227,15 +236,20 @@ routeDirectionsResult.body.routes.forEach(({ summary, legs }) => {
 
 Azure Maps currently provides two forms of route optimizations:
 
-- Optimizations based on the requested route type, without changing the order of waypoints. You can find the [supported route types here](https://docs.microsoft.com/rest/api/maps/route/post-route-directions?tabs=HTTP#routetype).
+- Optimizations based on the requested route type, without changing the order of waypoints. You can find the [supported route types here](https://learn.microsoft.com/rest/api/maps/route/post-route-directions?tabs=HTTP#routetype).
 - Traveling salesman optimization, which changes the order of the waypoints to obtain the best order to visit each stop
 
 For multi-stop routing, up to 150 waypoints may be specified in a single route request. The starting and ending coordinate locations can be the same, as would be the case with a round trip. But you need to provide at least one additional waypoint to make the route calculation. Waypoints can be added to the query in-between the origin and destination coordinates.
 
 If you want to optimize the best order to visit the given waypoints, then you need to specify `computeBestWaypointOrder=true`. This scenario is also known as the traveling salesman optimization problem.
 
-```javascript
-const { toColonDelimitedLatLonString, isUnexpected } = require("@azure-rest/maps-route");
+```ts snippet:ReadmeSampleRouteDirectionsOptimize
+import { DefaultAzureCredential } from "@azure/identity";
+import MapsRoute, { toColonDelimitedLatLonString, isUnexpected } from "@azure-rest/maps-route";
+
+const credential = new DefaultAzureCredential();
+const client = MapsRoute(credential, "<maps-account-client-id>");
+
 const routeDirectionsResult = await client.path("/route/directions/{format}", "json").get({
   queryParameters: {
     query: toColonDelimitedLatLonString([
@@ -257,13 +271,13 @@ if (isUnexpected(routeDirectionsResult)) {
   throw routeDirectionsResult.body.error;
 }
 
-const { summary } = routeDirectionsResult.body.routes[0]; 
+const { summary } = routeDirectionsResult.body.routes[0];
 console.log(
-  `The optimized distance is ${summary.lengthInMeters} meters, and it takes ${summary.travelTimeInSeconds} seconds.`
+  `The optimized distance is ${summary.lengthInMeters} meters, and it takes ${summary.travelTimeInSeconds} seconds.`,
 );
 console.log("The route is optimized by: ");
 routeDirectionsResult.body.optimizedWaypoints.forEach(
-  ({ providedIndex, optimizedIndex }) => `Moving index ${providedIndex} to ${optimizedIndex}`
+  ({ providedIndex, optimizedIndex }) => `Moving index ${providedIndex} to ${optimizedIndex}`,
 );
 ```
 
@@ -273,8 +287,8 @@ routeDirectionsResult.body.optimizedWaypoints.forEach(
 
 Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the `AZURE_LOG_LEVEL` environment variable to `info`. Alternatively, logging can be enabled at runtime by calling `setLogLevel` in the `@azure/logger`:
 
-```javascript
-const { setLogLevel } = require("@azure/logger");
+```ts snippet:SetLogLevel
+import { setLogLevel } from "@azure/logger";
 
 setLogLevel("info");
 ```
@@ -293,15 +307,15 @@ If you'd like to contribute to this library, please read the [contributing guide
 
 - [Microsoft Azure SDK for JavaScript](https://github.com/Azure/azure-sdk-for-js)
 
-![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-js%2Fsdk%2Fmaps%2Fmaps-route-rest%2FREADME.png)
+
 
 [source_code]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-route-rest
 [npm_link]: https://www.npmjs.com/package/@azure-rest/maps-route
-[api_ref]: https://docs.microsoft.com/javascript/api/@azure-rest/maps-route
+[api_ref]: https://learn.microsoft.com/javascript/api/@azure-rest/maps-route
 [samples]: https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/maps/maps-route-rest/samples
-[azure_cli]: https://docs.microsoft.com/cli/azure
+[azure_cli]: https://learn.microsoft.com/cli/azure
 [azure_sub]: https://azure.microsoft.com/free/
 [azure_portal]: https://portal.azure.com
-[azure_powershell]: https://docs.microsoft.com/powershell/module/az.maps/new-azmapsaccount
+[azure_powershell]: https://learn.microsoft.com/powershell/module/az.maps/new-azmapsaccount
 [azure_identity]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/identity/identity
 [defaultazurecredential]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/identity/identity#defaultazurecredential