Guía para desarrolladores del SDK de REST de JavaScript y TypeScript (versión preliminar)

Artículo
01/27/2024

El SDK de REST de JavaScript/TypeScript de Azure Maps (SDK de JavaScript) es compatible con la búsqueda mediante el servicio Search de Azure Maps, como la búsqueda de una dirección, la búsqueda de los límites de una ciudad o un país y la búsqueda por coordenadas. Este artículo le ayudará a empezar a crear aplicaciones compatibles con la ubicación que incorporan la eficacia de Azure Maps.

Nota:

El SDK de JavaScript de Azure Maps admite la versión LTS de Node.js. Para obtener más información, consulte Grupo de trabajo de la versión de Node.js.

Requisitos previos

Una cuenta de Azure Maps.
Una clave de suscripción u otra forma de Autenticación con Azure Maps.
Node.js.

Sugerencia

Puede crear una cuenta de Azure Maps mediante programación. A continuación se muestra un ejemplo mediante la CLI de Azure:

az maps account create --kind "Gen2" --account-name "myMapAccountName" --resource-group "<resource group>" --sku "G2"

Crear un proyecto de Node.js

En el ejemplo siguiente se crea un directorio y, luego, un programa de Node.js denominado mapsDemo mediante npm:

mkdir mapsDemo
cd mapsDemo
npm init

Instalación del paquete de búsqueda

Para usar el SDK de JavaScript de Azure Maps, deberá instalar el paquete de búsqueda. Cada uno de los servicios Azure Maps, como la búsqueda, el enrutamiento, la representación y la geolocalización, se encuentran en su propio paquete.

npm install @azure-rest/maps-search

Una vez que haya instalado el paquete, cree un archivo search.js en el directorio mapsDemo:

mapsDemo
+-- package.json
+-- package-lock.json
+-- node_modules/
+-- search.js

Servicios de Azure Maps

Nombre del servicio	paquetes npm	Ejemplos
Búsqueda	@azure-rest/maps-search	ejemplos de búsqueda
Route	@azure-rest/maps-route	Ejemplos de rutas
Representar	@azure-rest/maps-render	Ejemplo de representación
Geolocalización	@azure-rest/maps-geolocation	ejemplo de geolocalización

Creación y autenticación de un objeto MapsSearchClient

Necesita un objeto credential para la autenticación cuando cree el objeto MapsSearchClient que se usa para acceder a las API de búsqueda de Azure Maps. Puede usar una credencial de Microsoft Entra o una clave de suscripción de Azure para autenticarse. Para obtener más información sobre la autenticación, consulte Autenticación con Azure Maps.

Sugerencia

El objeto MapsSearchClient es la interfaz principal para los desarrolladores que usan la biblioteca de búsqueda de Azure Maps. Consulte Biblioteca cliente de búsqueda de Azure Maps para obtener más información sobre los métodos de búsqueda disponibles.

Uso de la credencial de Microsoft Entra

Puede autenticarse con Microsoft Entra ID mediante la biblioteca de identidades de Azure. Para usar el proveedor de DefaultAzureCredential, debe instalar el paquete @azure/identity:

npm install @azure/identity

Debe registrar la nueva aplicación de Microsoft Entra y conceder acceso a Azure Maps mediante la asignación del rol necesario a la entidad de servicio. Para más información, consulte Hospedaje de un demonio en recursos que no son de Azure. Se devuelve el id. de aplicación (cliente), un id. de directorio (inquilino) y un secreto de cliente. Copie estos valores y guárdelos en lugar seguro. Los necesitará en los pasos siguientes.

Establezca los valores del identificador de aplicación (cliente), el identificador de directorio (inquilino) y el secreto de cliente de la aplicación de Microsoft Entra, así como el identificador de cliente del recurso de asignación, como variables de entorno:

Variable de entorno	Descripción
AZURE_CLIENT_ID	Identificador de aplicación (cliente) de la aplicación registrada
AZURE_CLIENT_SECRET	Valor del secreto de cliente de la aplicación registrada
AZURE_TENANT_ID	Identificador de directorio (inquilino) de la aplicación registrada
MAPS_CLIENT_ID	Identificador de cliente de la cuenta de Azure Maps

Puede usar un archivo .env para estas variables. Debe instalar el paquete dotenv:

npm install dotenv

Después, agregue un archivo .env en el directorio mapsDemo y especifique estas propiedades:

AZURE_CLIENT_ID="<client-id>"
AZURE_CLIENT_SECRET="<client-secret>"
AZURE_TENANT_ID="<tenant-id>"
MAPS_CLIENT_ID="<maps-client-id>"

Una vez que se hayan creado las variables de entorno, puede acceder a ellas en el código JavaScript:

const MapsSearch = require("@azure-rest/maps-search").default; 
const { DefaultAzureCredential } = require("@azure/identity"); 
require("dotenv").config(); 
 
const credential = new DefaultAzureCredential(); 
const client = MapsSearch(credential, process.env.MAPS_CLIENT_ID);

Uso de una credencial de clave de suscripción

Puede autenticarse con la clave de suscripción de Azure Maps. Encontrará la clave de suscripción en la sección Autenticación de la cuenta de Azure Maps, como se muestra en la captura de pantalla siguiente:

Es necesario pasar la clave de suscripción a la clase AzureKeyCredential proporcionada por el Azure Core Authentication Package. Por motivos de seguridad, es mejor especificar la clave como una variable de entorno que incluirla en el código fuente.

Para ello, use un archivo .env para almacenar la variable de la clave de suscripción. Debe instalar el paquete dotenv para recuperar el valor:

npm install dotenv

Después, agregue un archivo .env en el directorio mapsDemo y especifique la propiedad:

MAPS_SUBSCRIPTION_KEY="<subscription-key>"

Una vez que se haya creado la variable de entorno, puede acceder a ella en el código JavaScript:

const MapsSearch = require("@azure-rest/maps-search").default;
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

const credential = new AzureKeyCredential(process.env.MAPS_SUBSCRIPTION_KEY);
const client = MapsSearch(credential);

Uso de una credencial de token de firma de acceso compartido (SAS)

Los tokens de firma de acceso compartido (SAS) son tokens de autenticación creados con el formato JSON Web Token (JWT) y están firmados criptográficamente para demostrar la autenticación de una aplicación en la API de REST de Azure Maps.

Puede obtener los tokens SAS usando el paquete AzureMapsManagementClient.accounts.listSas. Siga la sección Creación y autenticación de un AzureMapsManagementClient para configurarlo primero.

En segundo lugar, siga Identidades administradas para Azure Maps para crear una identidad administrada para su cuenta de Azure Maps. Copie el id. de entidad de seguridad (id. de objeto) de la identidad administrada.

A continuación, instale el paquete Azure Core Authentication Package para usar AzureSASCredential:

npm install @azure/core-auth

Por último, puede usar los tokens SAS para autenticar al cliente:

  const MapsSearch = require("@azure-rest/maps-search").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 = MapsSearch(sasCredential);

Codificación geográfica

El siguiente fragmento de código demuestra cómo, en una sencilla aplicación de consola, importar el paquete @azure-rest/maps-search y obtener las coordenadas de una dirección usando la consulta GetGeocoding:

const MapsSearch = require("@azure-rest/maps-search").default;
const { isUnexpected } = require("@azure-rest/maps-search");
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

async function main() {
  const credential = new AzureKeyCredential(
    process.env. MAPS_SUBSCRIPTION_KEY
  );
  const client = MapsSearch(credential);

  const response = await client.path("/geocode", "json").get({
    queryParameters: {
      query: "1301 Alaskan Way, Seattle, WA 98101, US",
    },
  });
  if (isUnexpected(response)) {
    throw response.body.error;
  }
  const [ lon, lat ] = response.body.features[0].geometry.coordinates;
  console.log(`The coordinate is: (${lat}, ${lon})`);
}

main().catch((err) => {
  console.error(err);
});

El fragmento de código anterior muestra cómo usar el método MapsSearch de la biblioteca cliente de Azure Maps Search para crear un objeto client con las credenciales de Azure. Puede usar la clave de suscripción de Azure Maps o la credencial de Microsoft Entra. El parámetro path especifica el punto de conexión de la API, que en este caso es "/geocode". El método get envía una solicitud HTTP GET con los parámetros de consulta. La consulta busca la coordenada de "1301 Alaskan Way, Seattle, WA 98101, US". El SDK devuelve los resultados como un objeto GeocodingResponseOutput y los escribe en la consola. Los resultados se ordenan por puntuación de confianza en este ejemplo y solo se muestra el primer resultado en la pantalla. Para más información, vea GetGeocoding.

Ejecute search.js con Node.js:

node search.js

Geocodificación inversa por lotes

La búsqueda de Azure Maps también proporciona algunos métodos de consulta por lotes. En el ejemplo siguiente se muestra cómo llamar al método de búsqueda inversa por lotes:

  const batchItems = [
    // This is an invalid query
    { coordinates: [2.294911, 148.858561] },
    {
      coordinates: [-122.34255, 47.6101],
    },
    { coordinates: [-122.33817, 47.6155] },
  ];
  const response = await client.path("/reverseGeocode:batch").post({
    body: { batchItems },
  });

En este ejemplo, se incluyen tres coordenadas en el batchItems del cuerpo de la solicitud. El primer elemento no es válido, consulte Control de solicitudes con error para ver un ejemplo en el que se muestra cómo controlar el elemento no válido.

Una vez que reciba la respuesta, podrá registrarla:

 
function logResponseBody(resBody) {
  const { summary, batchItems } = resBody;

  const { totalRequests, successfulRequests } = summary;
  console.log(`${successfulRequests} out of ${totalRequests} requests are successful.`);

  batchItems.forEach(({ response }, idx) => {
    if (response.error) {
      console.log(`Error in ${idx + 1} request: ${response.error.message}`);
    } else {
      console.log(`Results in ${idx + 1} request:`);
      response.features.forEach((feature) => {
        console.log(`  ${feature.properties.address.freeformAddress}`);
      });
    }
  });
}

Control de solicitudes con error

Para controlar las solicitudes con error, consulte la propiedad error del elemento de lote de respuesta. Consulte la función logResponseBody en el ejemplo de búsqueda inversa por lotes completos que se muestra a continuación.

Ejemplo completo de búsqueda inversa por lotes

Código completo del ejemplo de búsqueda inversa por lotes de direcciones:

const MapsSearch = require("@azure-rest/maps-search").default,
  { isUnexpected } = require("@azure-rest/maps-search");
const { AzureKeyCredential } = require("@azure/core-auth");
require("dotenv").config();

async function main() {
  const credential = new AzureKeyCredential(process.env.MAPS_SUBSCRIPTION_KEY);
  const client = MapsSearch(credential);

  const batchItems = [
    // This is an invalid query
    { coordinates: [2.294911, 148.858561] },
    {
      coordinates: [-122.34255, 47.6101],
    },
    { coordinates: [-122.33817, 47.6155] },
  ];

  const response = await client.path("/reverseGeocode:batch").post({
    body: { batchItems },
  });

  if (isUnexpected(response)) {
    throw response.body.error;
  }

  logResponseBody(resumeResponse.body);
}

function logResponseBody(resBody) {
  const { summary, batchItems } = resBody;

  const { totalRequests, successfulRequests } = summary;
  console.log(`${successfulRequests} out of ${totalRequests} requests are successful.`);

  batchItems.forEach(({ response }, idx) => {
    if (response.error) {
      console.log(`Error in ${idx + 1} request: ${response.error.message}`);
    } else {
      console.log(`Results in ${idx + 1} request:`);
      response.features.forEach((feature) => {
        console.log(`  ${feature.properties.address.freeformAddress}`);
      });
    }
  });
} 

main().catch(console.error);

Uso del SDK V1

Estamos trabajando para que todas las características de la V1 estén disponibles en la V2, hasta entonces, instale los siguientes paquetes SDK de la V1 si los necesita:

npm install @azure-rest/map-search-v1@npm:@azure-rest/map-search@^1.0.0
npm install @azure-rest/map-search-v2@npm:@azure-rest/map-search@^2.0.0

A continuación, puede importar los dos paquetes:

const MapsSearchV1 = require("@azure-rest/map-search-v1").default;
const MapsSearchV2 = require("@azure-rest/map-search-v2").default;

En el ejemplo siguiente se muestra la creación de una función que acepta una dirección y busca las POI alrededor de ella. Use el SDK V2 para obtener las coordenadas de la dirección (/geocode) y el SDK V1 para buscar PDI a su alrededor (/search/nearby).

const MapsSearchV1 = require("@azure-rest/map-search-v1").default;
const MapsSearchV2 = require("@azure-rest/map-search-v2").default;
const { AzureKeyCredential } = require("@azure/core-auth");
const { isUnexpected: isUnexpectedV1 } = require("@azure-rest/maps-search-v1");
const { isUnexpected: isUnexpectedV2 } = require("@azure-rest/maps-search-v2");
require("dotenv").config();

/** Initialize the MapsSearchClient */
const clientV1 = MapsSearchV1(new AzureKeyCredential(process.env.MAPS_SUBSCRIPTION_KEY));
const clientV2 = MapsSearchV2(new AzureKeyCredential(process.env.MAPS_SUBSCRIPTION_KEY));

async function searchNearby(address) {
  /** Make a request to the geocoding API */
  const geocodeResponse = await clientV2
    .path("/geocode")
    .get({ queryParameters: { query: address } });
  /** Handle error response */
  if (isUnexpectedV2(geocodeResponse)) {
    throw geocodeResponse.body.error;
  }

  const [lon, lat] = geocodeResponse.body.features[0].geometry.coordinates;
  
  /** Make a request to the search nearby API */
  const nearByResponse = await clientV1.path("/search/nearby/{format}", "json").get({
    queryParameters: { lat, lon },
  });
  /** Handle error response */
  if (isUnexpectedV1(nearByResponse)) {
    throw nearByResponse.body.error;
  }
  /** Log response body */
  for(const results of nearByResponse.body.results) {
    console.log(
      `${result.poi ? result.poi.name + ":" : ""} ${result.address.freeformAddress}. (${
        result.position.lat
      }, ${result.position.lon})\n`
    );
  }
}

async function main(){
  searchNearBy("15127 NE 24th Street, Redmond, WA 98052");
}

main().catch((err) => {
    console.log(err);
})

Información adicional

Biblioteca cliente de búsqueda de Azure Maps para JavaScript y TypeScript.

Compartir a través de