Migrar a API de Obtenção de Metadados de Imagens do Bing Mapas

2024-05-20

Este artigo explica como você pode migrar a API Obter Metadados de Imagens (Get Imagery Metadata) do Bing Mapas para a API Obter Peças de Mapa (Get Map Tile) do Azure Mapas.

A API de Obtenção de Peças de Mapa do Azure Mapas fornece peças de mapa em formatos vetoriais ou raster para serem usadas no SDK da Web do Azure Mapas ou em controles de mapa de terceiros. Alguns blocos de exemplo que podem ser solicitados são a estrada do Azure Mapas, satélite/aéreo ou radar meteorológico.

Pré-requisitos

Uma conta do Azure
Uma conta do Azure Mapas
Uma chave de assinatura ou outra forma de autenticação no Azure Mapas

Diferenças notáveis

A API de Obtenção de Metadados de Imagens do Bing Mapas fornece metadados das peças de mapa no corpo da resposta HTML, incluindo um URL para você obter a imagem da peça (ImageUrl). A API de Obtenção de Peças de Mapa do Azure Mapas fornece a imagem de peças de mapa diretamente na resposta HTML, mas não inclui os metadados.
A API de Obtenção de Metadados de Imagens do Bing Mapas fornece metadados de mapas no corpo da resposta HTML, incluindo informações sobre a safra da peça (vintageStart e vintageEnd). A API de Obtenção de Peças de Mapa do Azure Mapas fornece informações sobre a safra de peças de mapa no cabeçalho da resposta (Data-Capture-Date-Range), em vez de no corpo da resposta HTML.
A API de Obtenção de Metadados de Peças de Imagens do Bing Mapas fornece metadados de imagens no corpo da resposta HTML, incluindo informações de direitos autorais para as imagens do mapa. Para a API de Obtenção de Peças de Mapa do Azure Mapas, as informações de atribuição de direitos autorais do mapa podem ser obtidas na API Obter Atribuição de Mapa do Azure Mapas. As informações de atribuição de direitos autorais devem ser exibidas no mapa de acordo com os Termos de Produto do Azure Mapas.
A API de Obtenção de Peças de Mapa do Azure Mapas não oferece os seguintes estilos de mapa da API de Obtenção de Metadados de Imagens do Bing Mapas: Streetside, Birdseye e Ordnance Survey.
Atualmente, a API de Obtenção de Peças de Mapa do Azure Mapas não oferece um estilo de mapa de satélite/aéreo com rótulos de estradas, como o estilo de mapa AerialWithLabelsOnDemand da API de Obtenção de Metadados de Imagens do Bing Mapas. No entanto, o SDK da Web do Azure Mapas oferece um estilo de mapa semelhante chamado satellite_road_labels.
A API de Obtenção de Metadados de Imagens do Bing Mapas oferece um tamanho de peça de 256 x 256 pixels. Com a API de Obtenção Peças de Mapa do Azure Mapas, você pode obter peças de 256 x 256 pixels e de 512 x 512 pixels. Para mais informações, confira MapTileSize.
A API de Obtenção de Metadados de Imagens do Bing Mapas oferece suporte aos formatos de resposta XML e JSON, enquanto a API de Obtenção de Peças de Mapa do Azure Mapas só oferece suporte ao JSON.
A API de Obtenção Metadados de Imagens do Bing Mapas oferece mapas base em estilos como estradas e satélite/híbrido, usando o parâmetro URI imagerySet. A API de Obtenção de Peças de Mapa do Azure Mapas fornece mapas base de ofertas semelhantes usando o parâmetro URI TilesetID. O Azure Mapas TilesetID não oferece suporte a peças AerialWithLabelsOnDemand ou AerialWithLabels na API de Obtenção de Peças de Mapa. As peças híbridas só estão disponíveis no Controle de Mapeamento do SDK da Web do Azure Mapas.
Ao contrário do Bing Mapas para Empresas, o Azure Mapas é um serviço global que permite especificar um escopo geográfico, limitando a residência de dados às áreas geográficas da Europa (UE) ou América do Norte (EUA). Todas as solicitações (incluindo dados de entrada) são processadas exclusivamente na área geográfica especificada. Para obter mais informações, confira Escopo geográfico do serviço do Azure Mapas.

Segurança e autenticação

O Bing Mapas para Empresas dá suporte somente à autenticação de chave de API. O Azure Mapas dá suporte a várias maneiras de autenticar suas chamadas à API, como uma chave de assinatura, o Microsoft Entra ID e o token de Assinatura de Acesso Compartilhado (SAS). Para obter mais informações sobre segurança e autenticação no Azure Mapas, confira Autenticação com o Azure Mapas e a seção Segurança na documentação da API de Obtenção de Peças de Mapa do Azure Mapas.

Parâmetros da solicitação

A tabela a seguir lista os parâmetros da solicitação Obter Metadados de Imagens do Bing Mapas e o equivalente no Azure Mapas:

Parâmetro de solicitação do Bing Mapas	Alias do parâmetro de solicitação do Bing Mapas	Parâmetro de solicitação do Azure Mapas	Obrigatório no Azure Mapas	Tipo de dados do Azure Mapas	Descrição
imagerySet	None	tilesetId	True	ID do Conjunto de Peças	O Azure Mapas tem alguns estilos de mapa que a API de Obtenção de Metadados de Imagens do Bing Mapas não tem. A API de Obtenção de Metadados de Imagens do Bing Mapas tem alguns estilos de mapa que o Azure Mapas não tem. Para mais informações sobre os estilos de mapa oferecidos pelo Azure Mapas, confira TilesetID.
centerPoint	None	x y	True	integer int32	Para mais informações sobre coordenadas X e Y, confira níveis de zoom e grade de peças.
culture	c	Linguagem	Falso	string	Para obter mais informações, confira Idiomas compatíveis com o Azure Mapas.
include	incl	NA	NA	NA	A única opção para esse parâmetro no Bing Mapas é `ImageryProviders`. Quando especificadas, as informações de atribuição sobre os provedores de imagens são retornadas na resposta e devem ser exibidas no mapa. Para a API de Obtenção de Peças de Mapa do Azure Mapas, as informações de atribuição de direitos autorais do mapa podem ser obtidas na API Obter Atribuição de Mapa do Azure Mapas. As informações de atribuição de direitos autorais devem ser exibidas no mapa de acordo com os Termos de Produto do Azure Mapas.
mapLayer	ml	NA	N/D	NA
orientation	dir	NA	NA	NA	Aplica-se ao estilo de mapa Birdseye do Bing Mapas, que não é compatível com o Azure Mapas.
uriScheme		NA	NA	NA
zoomLevel	zl	Zoom	True	integer int32	Para mais informações sobre coordenadas X e Y, confira níveis de zoom e grade de peças.

Para mais informações sobre os parâmetros de solicitação do Azure Mapas, confira parâmetros de URI.

Exemplos de solicitação

Solicitação da API Obter Metadados de Imagens do Bing Mapas:

http://dev.virtualearth.net/REST/V1/Imagery/Metadata/road/37.770864,-122.467217?zl=15&key={YourBingMapsKey}

Solicitação da API Obter Peças de Mapa do Azure Mapas:

https://atlas.microsoft.com/map/tile?api-version=2022-08-01&tilesetId=microsoft.base.&zoom=15&x=5236&y=12665&tileSize=256&subscription-key={Your-Azure-Maps-Subscription-key}

Campos de resposta

A tabela a seguir lista os campos que podem aparecer na resposta HTTP quando você executa a API Obter Metadados de Imagens do Bing Mapas e o equivalente no Azure Mapas:

Campo de resposta do Bing Mapas	Campo de resposta do Azure Mapas	Descrição
imageHeight (JSON) ImageWidth (XML)	Sem suporte	A API de Obtenção de Peças de Mapa do Azure Mapas fornece a imagem de peças de mapa diretamente na resposta HTML (string de imagem binária) e oferece tamanhos de peça de 256 x 256 e 512 x 512 pixels.
imageUrl (JSON) ImageUrl (XML)	Sem suporte	A API de Obtenção de Peças de Mapa do Azure Mapas fornece a imagem de peças de mapa diretamente na resposta HTML (cadeia de caracteres de imagem binária), em vez de uma URL de imagem.
imageUrlSubdomains (JSON) ImageUrlSubdomains (XML)	Sem suporte	A API de Obtenção de Peças de Mapa do Azure Mapas fornece a imagem de peças de mapa diretamente na resposta HTML (cadeia de caracteres de imagem binária), em vez de uma URL de imagem.
imageWidth (JSON) ImageWidth (XML)	Sem suporte	A API de Obtenção de Peças de Mapa do Azure Mapas fornece a imagem de peças de mapa diretamente na resposta HTML (string de imagem binária) e oferece tamanhos de peça de 256 x 256 e 512 x 512 pixels.
vintageEnd (JSON) VintageEnd (XML)	Sem suporte	A API de Obtenção de Peças de Mapa do Azure Mapas fornece informações sobre a safra de peças de mapa no cabeçalho da resposta (Data-Capture-Date-Range ¹), em vez de no corpo da resposta.
vintageStart (JSON) VintageStart (XML)	Sem suporte	A API de Obtenção de Peças de Mapa do Azure Mapas fornece informações sobre a safra de peças de mapa no cabeçalho da resposta (Data-Capture-Date-Range ¹), em vez de no corpo da resposta.
zoomMax (JSON) ZoonMax (XML)	Sem suporte	Para informações sobre níveis de zoom e zoom máximo com suporte por estilos de peças de mapa, confira níveis de zoom e grade de peça e TilesetID.
zoomMin (JSON) ZoomMin (XML)	Sem suporte	Para informações sobre níveis de zoom e zoom máximo com suporte por estilos de peças de mapa, confira níveis de zoom e grade de peça e TilesetID.

¹ Ao usar a API do Azure Mapas para obter imagens de satélite RGB, você também pode recuperar informações sobre a data de aquisição. A resposta HTTP inclui um cabeçalho chamado Data-Capture-Date-Range, que fornece um intervalo de datas que indica quando a imagem foi capturada. Por exemplo, ele pode aparecer como "31/7/2022-9/1/2023". Tenha em mente que as imagens de satélite geralmente abrangem um intervalo de datas devido ao processamento em lote e à junção de várias imagens de datas diferentes para criar mapas contínuos. Portanto, embora uma única data nem sempre seja aplicável, o intervalo de datas fornece informações sobre quando os dados da imagem foram coletados.

Para obter mais informações sobre os campos de resposta da API de Obtenção de Peças de Mapa do Azure Mapas, confira Respostas.

Exemplos de respostas

A amostra JSON a seguir mostra o que é retornado no corpo da resposta HTTP quando você executa a solicitação Obter Metadados de Imagens do Bing Mapas:

{ 
    "authenticationResultCode": "ValidCredentials", 
    "brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png", 
    "copyright": "Copyright © 2024 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.", 
    "resourceSets": [ 
        { 
            "estimatedTotal": 1, 
            "resources": [ 
                { 
                    "__type": "ImageryMetadata:http://schemas.microsoft.com/search/local/ws/rest/v1", 
                    "imageHeight": 256, 
                    "imageUrl": "http://ecn.t2.tiles.virtualearth.net/tiles/r023010203332102.jpeg?g=14374&mkt={culture}&shading=hill", 
                    "imageUrlSubdomains": null, 
                    "imageWidth": 256, 
                    "imageryProviders": null, 
                    "vintageEnd": "02 Dec 2019 GMT", 
                    "vintageStart": "02 Dec 2019 GMT", 
                    "zoomMax": 15, 
                    "zoomMin": 15 
                } 
            ] 
        } 
    ], 
    "statusCode": 200, 
    "statusDescription": "OK", 
    "traceId": "c0630758c8475d6f60d65af81b548c6f|MWH0032BEB|0.0.0.1" 
}

A amostra JSON a seguir mostra o que é retornado no corpo da resposta HTTP quando você executa uma solicitação Obter Peça de Mapa do Azure Mapas:

Código de status: 200

Content-Type: application/vnd.mapbox-vector-tile

Corpo da resposta

"binary image string"

Uso de transações

A API de Obtenção de Metadados de Imagens do Bing Mapas gera uma transação faturável por solicitação de API. A API de Obtenção de Peças de Mapa do Azure Mapas gera uma transação faturável para cada 15 peças. Para obter mais informações sobre transações do Azure Mapas, consulte Noções básicas sobre transações do Azure Mapas.

Informações adicionais

Para obter mais APIs de Renderização do Azure Mapas, confira:

Obter atribuição de mapa: use para obter informações de atribuição de direitos autorais de mapas de peças.
Obter Imagem Estática do Mapa: use para renderizar uma imagem retangular definida pelo usuário que contém uma seção de mapa.

Suporte

Fórum do Microsoft Q&A