Render - Get Map Static Image

Service:

Maps

API Version:

2022-08-01

Utilize para compor uma imagem retangular definida pelo utilizador que contenha uma secção de mapa com um nível de zoom entre 0 e 20.

O intervalo de resolução suportado para a imagem do mapa é de 1x1 a 8192x8192. Se estiver a decidir quando utilizar o serviço de imagens estáticas através do serviço de mosaicos de mapa, recomendamos que considere como pretende interagir com o mapa composto. Se os conteúdos do mapa forem relativamente inalterados, um mapa estático é uma boa opção. Se quiser suportar bastante zoom, deslocamento panorâmico e alteração do conteúdo do mapa, o serviço de mosaicos de mapa seria uma escolha melhor.

O serviço também fornece funcionalidades de Composição de Imagens para obter uma imagem estática de volta com dados adicionais, como; os pushpins e a geometria sobrepõem-se às seguintes capacidades.

• Especificar vários estilos de alfinete
• Tipos de geometria de círculo, polílina e polígono.

Veja Procedimentos para obter exemplos detalhados.

Nota : o parâmetro central ou bbox tem de ser fornecido à API.

Os intervalos Lat e Lon suportados ao utilizar o parâmetro bbox são os seguintes:

Nível de Zoom	Intervalo Máximo de Lon	Intervalo Máximo de Lat
0	360.0	170.0
1	360.0	170.0
2	360.0	170.0
3	360.0	170.0
4	360.0	170.0
5	180.0	85.0
6	90.0	42.5
7	45.0	21.25
8	22,5	10.625
9	11.25	5.3125
10	5.625	2.62625
11	2.8125	1.328125
12	1.40625	0.6640625
13	0.703125	0.33203125
14	0.3515625	0.166015625
15	0.17578125	0.0830078125
16	0.087890625	0.0415039063
17	0.0439453125	0.0207519531
18	0.0219726563	0.0103759766
19	0.0109863281	0.0051879883
20	0.0054931641	0.0025939941

GET https://atlas.microsoft.com/map/static/png?api-version=2022-08-01

With optional parameters:

GET https://atlas.microsoft.com/map/static/png?api-version=2022-08-01&layer={layer}&style={style}&zoom={zoom}&center={center}&bbox={bbox}&height={height}&width={width}&language={language}&view={view}&pins={pins}&path={path}

Parâmetros do URI

Name	Em	Necessário	Tipo	Description
format	path	True	RasterTileFormat	Formato pretendido da resposta. Valor possível: png.
api-version	query	True	string	Número da versão da API Azure Maps. A versão atual é 2022-08-01
bbox	query		number[]	Caixa delimitadora. Projeção utilizada – EPSG:3857. Formato: "minLon, minLat, maxLon, maxLat". Nota: o bbox ou o centro são parâmetros necessários. São mutuamente exclusivos. Não deve ser utilizado com altura ou largura. Os intervalos máximos permitidos para Lat e Lon são definidos para cada nível de zoom na tabela na parte superior desta página.
center	query		number[]	Coordenadas do ponto central. Formato: "lon,lat". Projeção utilizada EPSG:3857. Intervalo de longitude: -180 a 180. Intervalo de latitude: -85 a 85. Nota: o centro ou o bbox são parâmetros necessários. São mutuamente exclusivos.
height	query		integer int32	Altura da imagem resultante em píxeis. O intervalo é de 1 a 8192. A predefinição é 512. Não deve ser utilizado com bbox.
language	query		string	Idioma no qual os resultados da pesquisa devem ser devolvidos. Deve ser uma das etiquetas de linguagem IETF suportadas, não sensível a maiúsculas e minúsculas. Quando os dados no idioma especificado não estão disponíveis para um campo específico, é utilizado o idioma predefinido. Consulte idiomas suportados para obter detalhes.
layer	query		StaticMapLayer	Camada de mapa pedida. Se a camada estiver definida como etiquetas ou híbrida, o formato deve ser png.
path	query		string[]	Estilo de caminho e localizações. Utilize este parâmetro para adicionar opcionalmente linhas, polígonos ou círculos à imagem. O estilo de caminho descreve o aspeto da linha e o preenchimento. (Certifique-se de que codifica corretamente valores de codificação de URL deste parâmetro, uma vez que conterá carateres reservados, como pipes e pontuação.) O parâmetro path é suportado no SKU da conta Azure Maps a partir do S1. Várias instâncias do parâmetro de caminho permitem especificar múltiplas geometrias com os respetivos estilos. O número de parâmetros por pedido está limitado a 10 e o número de localizações está limitado a 100 por caminho. Para compor um círculo com raio de 100 metros e ponto central na latitude 45°N e longitude 122°W com o estilo predefinido, adicione o parâmetro querystring path=ra100||-122 45 Tenha em atenção que a longitude vem antes da latitude. Após a codificação do URL, será semelhante a path=ra100%7C%7C-122+45 Todos os exemplos aqui mostram o parâmetro de caminho sem codificação de URL, para maior clareza. Para compor uma linha, separe cada localização com um caráter de pipe. Por exemplo, utilize path=||-122 45|-119.5 43.2|-121.67 47.12 Para compor um polígono, a última localização tem de ser igual à localização inicial. Por exemplo, utilize path=||-122 45|-119.5 43.2|-121.67 47.12|-122 45 Os valores de longitude e latitude para localizações de linhas e polígonos podem estar entre -360 e 360 para permitir a composição de geometrias que atravessam o anti-meridiano. Modificadores de Estilo Pode modificar o aspeto do caminho ao adicionar modificadores de estilo. Estas são adicionadas antes das localizações. Os modificadores de estilo têm um nome de duas letras. Estes nomes abreviados são utilizados para ajudar a reduzir o comprimento do URL. Para alterar a cor do contorno, utilize o modificador de estilo "lc" e especifique a cor com o formato de cor HTML/CSS RGB, que é um número hexadecimal de seis dígitos (o formulário de três dígitos não é suportado). Por exemplo, para utilizar uma cor cor-de-rosa profunda que especificaria como #FF1493 no CSS, utilize path=lcFF1493||-122 45|-119.5 43.2 Podem ser combinados vários modificadores de estilo para criar um estilo visual mais complexo. lc0000FF|lw3|la0.60|fa0.50||-122.2 47.6|-122.2 47.7|-122.3 47.7|-122.3 47.6|-122.2 47.6 Resumo do Modificador de Estilos Modificador Description Intervalo lc Cor da linha 0000000 para FFFFFF fc Cor de preenchimento 0000000 para FFFFFF la Alfa de linha (opacidade) 0 a 1 fa Preenchimento alfa (opacidade) 0 a 1 lw Largura da linha Maior que 0 ra Raio circular (medidores) Maior que 0
pins	query		string[]	Estilo de pushpin e instâncias. Utilize este parâmetro para, opcionalmente, adicionar pushpins à imagem. O estilo pushpin descreve o aspeto dos pushpins e as instâncias especificam as coordenadas dos pinos pushpins e etiquetas opcionais para cada pino. (Certifique-se de que codifica corretamente valores de codificação de URL deste parâmetro, uma vez que conterá carateres reservados, como pipes e pontuação.) O SKU S0 da conta Azure Maps só suporta uma única instância do parâmetro de pins. Outros SKUs permitem que várias instâncias do parâmetro pins especifiquem múltiplos estilos de pin. Para compor um pushpin na latitude 45°N e longitude 122°W com o estilo de pushpin incorporado predefinido, adicione o parâmetro querystring pins=default||-122 45 Tenha em atenção que a longitude vem antes da latitude. Após a codificação do URL, será semelhante a pins=default%7C%7C-122+45 Todos os exemplos aqui mostram o parâmetro pins sem codificação de URL, para maior clareza. Para compor um pino em várias localizações, separe cada localização com um caráter de pipe. Por exemplo, utilize pins=default||-122 45|-119.5 43.2|-121.67 47.12 O SKU da conta de Azure Maps S0 só permite cinco pushpins. Outros SKUs de conta não têm esta limitação. Modificadores de Estilo Pode modificar o aspeto dos pinos ao adicionar modificadores de estilo. Estes são adicionados após o estilo, mas antes das localizações e etiquetas. Os modificadores de estilo têm um nome de duas letras. Estes nomes abreviados são utilizados para ajudar a reduzir o comprimento do URL. Para alterar a cor do pushpin, utilize o modificador de estilo "co" e especifique a cor com o formato de cor HTML/CSS RGB, que é um número hexadecimal de seis dígitos (o formulário de três dígitos não é suportado). Por exemplo, para utilizar uma cor cor-de-rosa profunda que especificaria como #FF1493 no CSS, utilize pins=default|coFF1493||-122 45 Etiquetas pushpin Para adicionar uma etiqueta aos pinos, coloque a etiqueta em plicas imediatamente antes das coordenadas. Por exemplo, para etiquetar três pinos com os valores "1", "2" e "3", utilize pins=default||'1'-122 45|'2'-119.5 43.2|'3'-121.67 47.12 Existe um estilo de pushpin incorporado chamado "nenhum" que não apresenta uma imagem pushpin. Pode utilizá-lo se quiser apresentar etiquetas sem qualquer imagem de afixação. Por exemplo, pins=none||'A'-122 45|'B'-119.5 43.2 Para alterar a cor das etiquetas pushpin, utilize o modificador de estilo de cor de etiqueta "lc". Por exemplo, para utilizar pinos cor-de-rosa com etiquetas pretas, utilize pins=default|coFF1493|lc000000||-122 45 Para alterar o tamanho das etiquetas, utilize o modificador de estilo de tamanho de etiqueta "ls". O tamanho da etiqueta representa a altura aproximada do texto da etiqueta em píxeis. Por exemplo, para aumentar o tamanho da etiqueta para 12, utilize pins=default|ls12||'A'-122 45|'B'-119 43 As etiquetas estão centradas na "âncora de etiqueta" pushpin. A localização da âncora está predefinida para os pushpins incorporados e está no centro superior dos pushpins personalizados (consulte abaixo). Para substituir a âncora de etiquetas, utilize o modificador de estilo "la" e forneça coordenadas de pixéis X e Y para a âncora. Estas coordenadas são relativas ao canto superior esquerdo da imagem pushpin. Os valores X positivos movem a âncora para a direita e os valores Y positivos movem a âncora para baixo. Por exemplo, para posicionar a âncora de etiquetas 10 píxeis à direita e 4 píxeis acima do canto superior esquerdo da imagem pushpin, utilize pins=default|la10 -4||'A'-122 45|'B'-119 43 Pushpins Personalizados Para utilizar uma imagem pushpin personalizada, utilize a palavra "personalizado" como o nome do estilo do pin e, em seguida, especifique um URL após a localização e as informações da etiqueta. Utilize dois carateres de pipe para indicar que acabou de especificar localizações e que está a iniciar o URL. Por exemplo, pins=custom||-122 45||http://contoso.com/pushpins/red.png Após a codificação do URL, teria o seguinte aspeto pins=custom%7C%7C-122+45%7C%7Chttp%3A%2F%2Fcontoso.com%2Fpushpins%2Fred.png Por predefinição, as imagens pushpin personalizadas são desenhadas centradas nas coordenadas do pin. Normalmente, isto não é ideal, pois obscurece a localização que está a tentar realçar. Para substituir a localização da âncora da imagem do pin, utilize o modificador de estilo "an". Esta ação utiliza o mesmo formato que o modificador de estilo de âncora de etiqueta "la". Por exemplo, se a sua imagem de afixação personalizada tiver a ponta do pino no canto superior esquerdo da imagem, pode definir a âncora para esse local utilizando pins=custom|an0 0||-122 45||http://contoso.com/pushpins/red.png Nota: se utilizar o modificador de cores "co" com uma imagem pushpin personalizada, a cor especificada substituirá os canais RGB dos píxeis na imagem, mas deixará o canal alfa (opacidade) inalterado. Normalmente, isto só seria feito com uma imagem personalizada de cores sólidas. Dimensionamento, Rotação e Opacidade Pode tornar os pushpins e as respetivas etiquetas maiores ou menores com o modificador de estilo de escala "sc". Este é um valor maior que zero. Um valor de 1 é a escala padrão. Os valores maiores do que 1 aumentarão os pinos e os valores inferiores a 1 irão torná-los mais pequenos. Por exemplo, para desenhar os pushpins 50% maiores do que o normal, utilize pins=default|sc1.5||-122 45 Pode rodar os pushpins e as respetivas etiquetas com o modificador de estilo de rotação "ro". Este é um número de graus de rotação no sentido dos ponteiros do relógio. Utilize um número negativo para rodar no sentido contrário ao dos ponteiros do relógio. Por exemplo, para rodar os pushpins 90 graus no sentido dos ponteiros do relógio e duplicar o tamanho, utilize pins=default|ro90|sc2||-122 45 Pode tornar os pushpins e as etiquetas parcialmente transparentes ao especificar o modificador de estilo alfa "al". Este é um número entre 0 e 1 que indica a opacidade dos pushpins. Zero torna-os completamente transparentes (e não visíveis) e 1 torna-os completamente opacos (que é a predefinição). Por exemplo, para tornar os pushpins e as respetivas etiquetas apenas 67% opacos, utilize pins=default|al.67||-122 45 Resumo do Modificador de Estilos Modificador Description Intervalo al Alfa (opacidade) 0 a 1 mar Afixar âncora * co Afixar cor 0000000 para FFFFFF la Âncora de etiquetas * lc Cor da etiqueta 0000000 para FFFFFF ls Tamanho da etiqueta Maior que 0 ro Rotação -360 a 360 sc Escala Maior que 0 As coordenadas X e Y podem estar em qualquer lugar dentro da imagem de afixação ou de uma margem à sua volta. O tamanho da margem é o mínimo da largura e altura do pino.
style	query		MapImageStyle	Estilo de mapa a ser devolvido. Os valores possíveis são principais e escuros.
view	query		LocalizedMapView	O parâmetro Ver (também denominado parâmetro "região do utilizador") permite-lhe mostrar os mapas corretos para um determinado país/região para regiões geopolíticos disputadas. Diferentes países/regiões têm vistas diferentes dessas regiões e o parâmetro Ver permite que a sua aplicação cumpra a vista exigida pelo país/região que a sua aplicação irá servir. Por predefinição, o parâmetro Ver está definido como "Unificado", mesmo que não o tenha definido no pedido. É da sua responsabilidade determinar a localização dos seus utilizadores e, em seguida, definir o parâmetro Ver corretamente para essa localização. Em alternativa, tem a opção de definir "View=Auto", que irá devolver os dados do mapa com base no endereço IP do pedido. O parâmetro Ver no Azure Maps tem de ser utilizado em conformidade com as leis aplicáveis, incluindo as relativas ao mapeamento, do país/região onde são disponibilizados mapas, imagens e outros dados e conteúdos de terceiros aos quais está autorizado a aceder através de Azure Maps. Exemplo: view=IN. Consulte Vistas Suportadas para obter detalhes e para ver as Vistas disponíveis.
width	query		integer int32	Largura da imagem resultante em píxeis. O intervalo é de 1 a 8192. A predefinição é 512. Não deve ser utilizado com bbox.
zoom	query		integer int32	Nível de zoom pretendido do mapa. O valor do zoom tem de estar no intervalo: 0-20 (inclusive). O valor predefinido é 12. Consulte Níveis de Zoom e Grelha de Mosaicos para obter detalhes.

Cabeçalho do Pedido

Name	Necessário	Tipo	Description
x-ms-client-id		string	Especifica a conta que se destina à utilização em conjunto com o modelo de segurança Microsoft Entra ID. Representa um ID exclusivo para a conta Azure Maps e pode ser obtido a partir da API de Conta do plano de gestão Azure Maps. Para utilizar Microsoft Entra ID segurança no Azure Maps consulte os seguintes artigos para obter orientações.

Respostas

Name	Tipo	Description
200 OK	object	Esta imagem é devolvida a partir de uma chamada Obter Imagem Estática de Mapa com êxito Media Types: "application/json", "image/jpeg", "image/png", "image/pbf", "application/vnd.mapbox-vector-tile" Headers Content-Type: string
Other Status Codes	ErrorResponse	Ocorreu um erro inesperado. Media Types: "application/json", "image/jpeg", "image/png", "image/pbf", "application/vnd.mapbox-vector-tile"

Segurança

AADToken

Estes são os fluxos Microsoft Entra OAuth 2.0. Quando emparelhado com o controlo de acesso baseado em funções do Azure, pode ser utilizado para controlar o acesso às APIs REST Azure Maps. Os controlos de acesso baseados em funções do Azure são utilizados para designar o acesso a uma ou mais Azure Maps conta de recursos ou sub-recursos. Qualquer utilizador, grupo ou principal de serviço pode ter acesso através de uma função incorporada ou de uma função personalizada composta por uma ou mais permissões para Azure Maps APIs REST.

Para implementar cenários, recomendamos que veja os conceitos de autenticação. Em resumo, esta definição de segurança fornece uma solução para modelar aplicações através de objetos com capacidade de controlo de acesso em APIs e âmbitos específicos.

Notas

• Esta definição de segurança requer a utilização do x-ms-client-id cabeçalho para indicar a que recurso Azure Maps a aplicação está a pedir acesso. Isto pode ser adquirido a partir da API de gestão do Maps.

O Authorization URL é específico da instância da cloud pública do Azure. As clouds soberanas têm URLs de Autorização exclusivos e configurações de Microsoft Entra ID. * O controlo de acesso baseado em funções do Azure está configurado a partir do plano de gestão do Azure através de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST. * A utilização do SDK Web Azure Maps permite a configuração baseada na configuração de uma aplicação para vários casos de utilização.

• Para obter mais informações sobre plataforma de identidades da Microsoft, consulte plataforma de identidades da Microsoft descrição geral.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

Esta é uma chave partilhada que é aprovisionada ao criar um recurso Azure Maps através do plano de gestão do Azure através de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.

Com esta chave, qualquer aplicação está autorizada a aceder a todas as APIs REST. Por outras palavras, estas podem atualmente ser tratadas como chaves mestras da conta para a qual são emitidas.

Para aplicações expostas publicamente, a nossa recomendação é utilizar o acesso servidor a servidor das APIs REST Azure Maps onde esta chave pode ser armazenada de forma segura.

Type: apiKey
In: header

SAS Token

Este é um token de assinatura de acesso partilhado criado a partir da operação Listar SAS no recurso Azure Maps através do plano de gestão do Azure através de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.

Com este token, qualquer aplicação está autorizada a aceder com controlos de acesso baseados em funções do Azure e controlo detalhado para a expiração, taxa e regiões de utilização para o token específico. Por outras palavras, o Token de SAS pode ser utilizado para permitir que as aplicações controlem o acesso de uma forma mais segura do que a chave partilhada.

Para aplicações expostas publicamente, a nossa recomendação é configurar uma lista específica de origens permitidas no recurso da conta de Mapa para limitar o abuso de composição e renovar regularmente o Token de SAS.

Type: apiKey
In: header

Exemplos

Successful Static Image Request

Sample Request

HTTP

GET https://atlas.microsoft.com/map/static/png?api-version=2022-08-01&layer=basic&style=main&zoom=2&bbox=1.355233,42.982261,24.980233,56.526017

Sample Response

Status code:

200

Content-Type: image/png

Response Body

"{file}"

Definições

Name	Description
ErrorAdditionalInfo	Informações adicionais sobre o erro de gestão de recursos.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta a erros
LocalizedMapView	O parâmetro Ver (também denominado parâmetro "região do utilizador") permite-lhe mostrar os mapas corretos para um determinado país/região para regiões geopolíticos disputadas. Diferentes países/regiões têm vistas diferentes dessas regiões e o parâmetro Ver permite que a sua aplicação cumpra a vista exigida pelo país/região que a sua aplicação irá servir. Por predefinição, o parâmetro Ver está definido como "Unificado", mesmo que não o tenha definido no pedido. É da sua responsabilidade determinar a localização dos seus utilizadores e, em seguida, definir o parâmetro Ver corretamente para essa localização. Em alternativa, tem a opção de definir "View=Auto", que irá devolver os dados do mapa com base no endereço IP do pedido. O parâmetro Ver no Azure Maps tem de ser utilizado em conformidade com as leis aplicáveis, incluindo as relativas ao mapeamento, do país/região onde são disponibilizados mapas, imagens e outros dados e conteúdos de terceiros aos quais está autorizado a aceder através de Azure Maps. Exemplo: view=IN. Consulte As Vistas Suportadas para obter detalhes e ver as Vistas disponíveis.
MapImageStyle	Estilo de mapa a ser devolvido. Os valores possíveis são principais e escuros.
RasterTileFormat	Formato pretendido da resposta. Valor possível: png.
StaticMapLayer	Camada de mapa pedida. Se a camada estiver definida como etiquetas ou híbrida, o formato deve ser png.

ErrorAdditionalInfo

Informações adicionais sobre o erro de gestão de recursos.

Name	Tipo	Description
info	object	As informações adicionais.
type	string	O tipo de informações adicionais.

ErrorDetail

O detalhe do erro.

Name	Tipo	Description
additionalInfo	ErrorAdditionalInfo[]	As informações adicionais do erro.
code	string	O código de erro.
details	ErrorDetail[]	Os detalhes do erro.
message	string	A mensagem de erro.
target	string	O destino do erro.

ErrorResponse

Resposta a erros

Name	Tipo	Description
error	ErrorDetail	O objeto de erro.

LocalizedMapView

O parâmetro Ver (também denominado parâmetro "região do utilizador") permite-lhe mostrar os mapas corretos para um determinado país/região para regiões geopolíticos disputadas. Diferentes países/regiões têm vistas diferentes dessas regiões e o parâmetro Ver permite que a sua aplicação cumpra a vista exigida pelo país/região que a sua aplicação irá servir. Por predefinição, o parâmetro Ver está definido como "Unificado", mesmo que não o tenha definido no pedido. É da sua responsabilidade determinar a localização dos seus utilizadores e, em seguida, definir o parâmetro Ver corretamente para essa localização. Em alternativa, tem a opção de definir "View=Auto", que irá devolver os dados do mapa com base no endereço IP do pedido. O parâmetro Ver no Azure Maps tem de ser utilizado em conformidade com as leis aplicáveis, incluindo as relativas ao mapeamento, do país/região onde são disponibilizados mapas, imagens e outros dados e conteúdos de terceiros aos quais está autorizado a aceder através de Azure Maps. Exemplo: view=IN.

Consulte As Vistas Suportadas para obter detalhes e ver as Vistas disponíveis.

Name	Tipo	Description
AE	string	Emirados Árabes Unidos (Vista Árabe)
AR	string	Argentina (Vista Argentina)
Auto	string	Devolver os dados do mapa com base no endereço IP do pedido.
BH	string	Barém (Vista Árabe)
IN	string	Índia (Vista Indiana)
IQ	string	Iraque (Vista Árabe)
JO	string	Jordânia (Vista Árabe)
KW	string	Kuwait (Vista Árabe)
LB	string	Líbano (Vista Árabe)
MA	string	Marrocos (Vista Marroquina)
OM	string	Omã (Vista Árabe)
PK	string	Paquistão (Vista Paquistanesa)
PS	string	Autoridade Palestiniana (Vista Árabe)
QA	string	Qatar (Vista Árabe)
SA	string	Arábia Saudita (Vista Árabe)
SY	string	Síria (Vista Árabe)
Unified	string	Vista Unificada (Outros)
YE	string	Iémen (Vista Árabe)

MapImageStyle

Estilo de mapa a ser devolvido. Os valores possíveis são principais e escuros.

Name	Tipo	Description
dark	string	Versão cinzenta escura do estilo principal Azure Maps
main	string	Azure Maps estilo principal

RasterTileFormat

Formato pretendido da resposta. Valor possível: png.

Name	Tipo	Description
png	string	Uma imagem no formato png. Suporta níveis de zoom de 0 a 18.

StaticMapLayer

Camada de mapa pedida. Se a camada estiver definida como etiquetas ou híbrida, o formato deve ser png.

Name	Tipo	Description
basic	string	Devolve uma imagem que contém todas as funcionalidades do mapa, incluindo polígonos, limites, estradas e etiquetas.
hybrid	string	Devolve uma imagem que contém limites, estradas e etiquetas e pode ser sobreposta noutros mosaicos (como imagens de satélite) para produzir mosaicos híbridos.
labels	string	Devolve uma imagem apenas das informações da etiqueta do mapa.