Render - Get Map Static Image

Service:

Maps

API Version:

2022-08-01

Use para renderizar uma imagem retangular definida pelo usuário que contém uma seção de mapa usando um nível de zoom que varia de 0 a 20.

O intervalo de resolução com suporte para a imagem de mapa é de 1x1 a 8192x8192. Se você estiver decidindo quando usar o serviço de imagem estática no serviço de bloco do mapa, talvez queira considerar como gostaria de interagir com o mapa renderizado. Se o conteúdo do mapa for relativamente inalterado, um mapa estático será uma boa opção. Se você quiser dar suporte a muito zoom, movimento panorâmico e alteração do conteúdo do mapa, o serviço de bloco do mapa seria uma opção melhor.

O serviço também fornece a funcionalidade de Composição de Imagem para obter uma imagem estática de volta com dados adicionais, como; pushpins e sobreposições de geometria com os seguintes recursos.

• Especificar vários estilos de pushpin
• Renderizar tipos de geometria de círculo, polilinha e polígono.

Consulte How-to-Guide para obter exemplos detalhados.

Observação : o parâmetro central ou bbox deve ser fornecido à API.

Os intervalos Lat e Lon com suporte ao usar 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 de URI

Nome	Em	Obrigatório	Tipo	Description
format	path	True	RasterTileFormat	Formato desejado da resposta. Valor possível: png.
api-version	query	True	string	Número de versão da API de Mapas Azure. A versão atual é 01-08-2022
bbox	query		number[]	Caixa delimitadora. Projeção usada – EPSG:3857. Formato: 'minLon, minLat, maxLon, maxLat'. Observação: bbox ou center são parâmetros obrigatórios. Eles são mutuamente exclusivos. Ele não deve ser usado 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 usada EPSG:3857. Intervalo de longitude: -180 a 180. Intervalo de latitude: -85 a 85. Observação: os parâmetros central ou bbox são obrigatórios. Eles são mutuamente exclusivos.
height	query		integer int32	Altura da imagem resultante em pixels. O intervalo é de 1 a 8192. O padrão é 512. Ele não deve ser usado com bbox.
language	query		string	Idioma no qual os resultados da pesquisa devem ser retornados. Deve ser uma das marcas de idioma IETF com suporte, que não diferencia maiúsculas de minúsculas. Quando os dados no idioma especificado não estão disponíveis para um campo específico, o idioma padrão é usado. Consulte Idiomas com suporte para obter detalhes.
layer	query		StaticMapLayer	Camada de mapa solicitada. Se a camada for definida como rótulos ou híbrido, o formato deverá ser png.
path	query		string[]	Estilo de caminho e locais. Use esse parâmetro para adicionar opcionalmente linhas, polígonos ou círculos à imagem. O estilo de caminho descreve a aparência da linha e do preenchimento. (Certifique-se de codificar corretamente valores de URL desse parâmetro, pois ele conterá caracteres reservados, como pipes e pontuação.) Há suporte para o parâmetro Path no SKU da conta Azure Mapas, começando pelo S1. Várias instâncias do parâmetro path permitem especificar várias geometrias com seus estilos. O número de parâmetros por solicitação é limitado a 10 e o número de locais é limitado a 100 por caminho. Para renderizar um círculo com raio de 100 metros e ponto central na latitude 45°N e longitude 122°W usando o estilo padrão, adicione o parâmetro querystring path=ra100||-122 45 Observe que a longitude vem antes da latitude. Após a codificação de URL, essa aparência será semelhante a path=ra100%7C%7C-122+45 Todos os exemplos aqui mostram o parâmetro path sem codificação de URL, para maior clareza. Para renderizar uma linha, separe cada local com um caractere de pipe. Por exemplo, use path=||-122 45|-119.5 43.2|-121.67 47.12 Para renderizar um polígono, o último local deve ser igual ao local inicial. Por exemplo, use path=||-122 45|-119.5 43.2|-121.67 47.12|-122 45 Os valores de longitude e latitude para locais de linhas e polígonos podem estar no intervalo de -360 a 360 para permitir a renderização de geometrias que cruzam o anti-meridiano. Modificadores de estilo Você pode modificar a aparência do caminho adicionando modificadores de estilo. Eles são adicionados antes dos locais. Cada um dos modificadores de estilo tem um nome de duas letras. Esses nomes abreviados são usados para ajudar a reduzir o comprimento da URL. Para alterar a cor da estrutura de tópicos, use o modificador de estilo 'lc' e especifique a cor usando o formato de cor HTML/CSS RGB, que é um número hexadecimal de seis dígitos (não há suporte para a forma de três dígitos). Por exemplo, para usar uma cor rosa profunda que você especificaria como #FF1493 no CSS, use path=lcFF1493||-122 45|-119.5 43.2 Vários modificadores de estilo podem ser combinados 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 estilo Modificador Descrição Intervalo Lc Cor da linha 000000 a FFFFFF fc Cor de preenchimento 000000 a FFFFFF la Linha alfa (opacidade) 0 a 1 fa Preenchimento alfa (opacidade) 0 a 1 Lw Largura da linha Maior que 0 Ra Raio do círculo (metros) Maior que 0
pins	query		string[]	Estilo de pino e instâncias. Use esse parâmetro para, opcionalmente, adicionar pinos à imagem. O estilo de pino descreve a aparência dos pinos e as instâncias especificam as coordenadas dos pinos e rótulos opcionais para cada pino. (Certifique-se de codificar corretamente valores de URL desse parâmetro, pois ele conterá caracteres reservados, como pipes e pontuação.) O SKU S0 da conta Azure Mapas dá suporte apenas a uma única instância do parâmetro pins. Outras SKUs permitem que várias instâncias do parâmetro pins especifiquem vários estilos de pin. Para renderizar um pino em latitude 45°N e longitude 122°W usando o estilo de pino interno padrão, adicione o parâmetro querystring pins=default||-122 45 Observe que a longitude vem antes da latitude. Após a codificação de URL, essa aparência 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 renderizar um pino em vários locais, separe cada local com um caractere de pipe. Por exemplo, use pins=default||-122 45|-119.5 43.2|-121.67 47.12 O SKU da conta de Azure Mapas S0 permite apenas cinco pinos. Outras SKUs de conta não têm essa limitação. Modificadores de estilo É possível modificar a aparência dos pinos adicionando modificadores de estilo. Eles são adicionados após o estilo, mas antes dos locais e rótulos. Cada um dos modificadores de estilo tem um nome de duas letras. Esses nomes abreviados são usados para ajudar a reduzir o comprimento da URL. Para alterar a cor do pino, use o modificador de estilo 'co' e especifique a cor usando o formato de cor HTML/CSS RGB, que é um número hexadecimal de seis dígitos (não há suporte para a forma de três dígitos). Por exemplo, para usar uma cor rosa profunda que você especificaria como #FF1493 no CSS, use pins=default|coFF1493||-122 45 Rótulos de pino Para adicionar um rótulo aos pinos, coloque o rótulo entre aspas simples pouco antes das coordenadas. Por exemplo, para rotular três pinos com os valores '1', '2' e '3', use pins=default||'1'-122 45|'2'-119.5 43.2|'3'-121.67 47.12 Há um estilo de pino interno chamado 'none' que não exibe uma imagem de pino. Você pode usar isso se quiser exibir rótulos sem nenhuma imagem de fixação. Por exemplo, pins=none||'A'-122 45|'B'-119.5 43.2 Para alterar a cor dos rótulos de pino, use o modificador de estilo de cor do rótulo 'lc'. Por exemplo, para usar pinos rosa com rótulos pretos, use pins=default|coFF1493|lc000000||-122 45 Para alterar o tamanho dos rótulos, use o modificador de estilo de tamanho de rótulo 'ls'. O tamanho do rótulo representa a altura aproximada do texto do rótulo em pixels. Por exemplo, para aumentar o tamanho do rótulo para 12, use pins=default|ls12||'A'-122 45|'B'-119 43 Os rótulos são centralizados no pushpin 'label anchor'. O local da âncora é predefinido para pinos internos e está no centro superior de pinos personalizados (veja abaixo). Para substituir a âncora de rótulo, use o modificador de estilo 'la' e forneça coordenadas de pixel X e Y para a âncora. Essas coordenadas são relativas ao canto superior esquerdo da imagem de pino. Os valores positivos X movem a âncora para a direita e os valores Y positivos movem a âncora para baixo. Por exemplo, para posicionar a âncora de rótulo 10 pixels para a direita e 4 pixels acima do canto superior esquerdo da imagem de pino, use pins=default|la10 -4||'A'-122 45|'B'-119 43 Pinos personalizados Para usar uma imagem de pushpin personalizada, use a palavra "personalizado" como o nome do estilo do pino e especifique uma URL após as informações de localização e rótulo. Use dois caracteres de pipe para indicar que você terminou de especificar locais e está iniciando a URL. Por exemplo, pins=custom||-122 45||http://contoso.com/pushpins/red.png Após a codificação de URL, isso teria a aparência pins=custom%7C%7C-122+45%7C%7Chttp%3A%2F%2Fcontoso.com%2Fpushpins%2Fred.png Por padrão, as imagens de pino personalizadas são desenhadas centralizada nas coordenadas do pino. Isso geralmente não é ideal, pois obscurece o local que você está tentando realçar. Para substituir o local de âncora da imagem de pino, use o modificador de estilo 'an'. Isso usa o mesmo formato que o modificador de estilo de âncora de rótulo 'la'. Por exemplo, se sua imagem de fixação personalizada tiver a ponta do pino no canto superior esquerdo da imagem, você poderá definir a âncora para esse ponto usando pins=custom|an0 0||-122 45||http://contoso.com/pushpins/red.png Observação: se você usar o modificador de cor 'co' com uma imagem de pino personalizada, a cor especificada substituirá os canais RGB dos pixels na imagem, mas deixará o canal alfa (opacidade) inalterado. Isso normalmente só seria feito com uma imagem personalizada de cor sólida. Escala, rotação e opacidade É possível criar pinos e rótulos maiores ou menores, usando o modificador de estilo de escala 'sc'. Esse é um valor maior que zero. Um valor de 1 é a escala padrão. Valores maiores que 1 tornarão os marcadores maiores e valores menores que 1 os tornarão menores. Por exemplo, para desenhar os pinos 50% maiores que o normal, use pins=default|sc1.5||-122 45 Você pode girar os pinos e seus rótulos usando o modificador de estilo de rotação 'ro'. Esse é um número de graus de rotação no sentido horário. Use um número negativo para girar no sentido anti-horário. Por exemplo, para girar os pinos 90 graus no sentido horário e dobrar seu tamanho, use pins=default|ro90|sc2||-122 45 Você pode tornar os pinos e seus rótulos parcialmente transparentes especificando o modificador de estilo alfa 'al'. Esse é um número entre 0 e 1 que indica a opacidade dos pinos. Zero os torna completamente transparentes (e não visíveis) e 1 os torna completamente opacos (que é o padrão). Por exemplo, para tornar os pinos e seus rótulos apenas 67% opacos, use pins=default|al.67||-122 45 Resumo do modificador de estilo Modificador Descrição Intervalo al Alfa (opacidade) 0 a 1 an Fixar âncora * co Cor do pino 000000 a FFFFFF la Âncora de rótulo * Lc Cor do rótulo 000000 a FFFFFF ls Tamanho do rótulo 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 pino ou uma margem ao redor dela. O tamanho da margem é o mínimo da largura e altura do pino.
style	query		MapImageStyle	Estilo de mapa a ser retornado. Os valores possíveis são main e escuros.
view	query		LocalizedMapView	O parâmetro View (também chamado de parâmetro "região do usuário") permite que você mostre os mapas corretos para um determinado país/região para regiões geopolíticas disputadas. Diferentes países/regiões têm diferentes exibições dessas regiões, e o parâmetro View permite que seu aplicativo cumpra a exibição exigida pelo país/região que seu aplicativo fornecerá. Por padrão, o parâmetro View é definido como "Unificado", mesmo que você não o tenha definido na solicitação. É sua responsabilidade determinar a localização dos usuários e, em seguida, definir o parâmetro View corretamente para esse local. Como alternativa, você tem a opção de definir 'View=Auto', que retornará os dados do mapa com base no endereço IP da solicitação. O parâmetro View em Azure Mapas deve ser usado em conformidade com as leis aplicáveis, incluindo aquelas relativas ao mapeamento, do país/região em que mapas, imagens e outros dados e conteúdo de terceiros que você está autorizado a acessar por meio de Azure Mapas é disponibilizado. Exemplo: view=IN. Consulte Modos de exibição com suporte para obter detalhes e para ver as Exibições disponíveis.
width	query		integer int32	Largura da imagem resultante em pixels. O intervalo é de 1 a 8192. O padrão é 512. Ele não deve ser usado com bbox.
zoom	query		integer int32	Nível de zoom desejado do mapa. O valor de zoom deve estar no intervalo: 0 a 20 (inclusivo). O valor padrão é 12. Consulte Níveis de Zoom e Grade de Blocos para obter detalhes.

Cabeçalho da solicitação

Nome	Obrigatório	Tipo	Description
x-ms-client-id		string	Especifica qual conta destina-se ao uso em conjunto com o modelo de segurança Microsoft Entra ID. Ele representa uma ID exclusiva para a conta Azure Mapas e pode ser recuperado da API de Conta do plano de gerenciamento Azure Mapas. Para usar Microsoft Entra ID segurança no Azure Mapas consulte os artigos a seguir para obter diretrizes.

Respostas

Nome	Tipo	Description
200 OK	object	Esta imagem é retornada de uma chamada bem-sucedida Obter Imagem Estática do Mapa Media Types: "application/json", "image/jpeg", "image/png", "image/pbf", "application/vnd.mapbox-vector-tile" Headers Content-Type: string
Other Status Codes	ErrorResponse	Erro inesperado. Media Types: "application/json", "image/jpeg", "image/png", "image/pbf", "application/vnd.mapbox-vector-tile"

Segurança

AADToken

Esses são os fluxos Microsoft Entra OAuth 2.0. Quando emparelhado com o controle de acesso baseado em função do Azure, ele pode ser usado para controlar o acesso às APIs REST Azure Mapas. Os controles de acesso baseados em função do Azure são usados para designar o acesso a uma ou mais Azure Mapas conta de recurso ou sub-recursos. Qualquer usuário, grupo ou entidade de serviço pode receber acesso por meio de uma função interna ou uma função personalizada composta por uma ou mais permissões para Azure Mapas APIs REST.

Para implementar cenários, recomendamos exibir conceitos de autenticação. Em resumo, essa definição de segurança fornece uma solução para modelar aplicativos por meio de objetos capazes de acessar o controle em APIs e escopos específicos.

Observações

• Essa definição de segurança requer o uso do x-ms-client-id cabeçalho para indicar a qual Azure Mapas recurso ao qual o aplicativo está solicitando acesso. Isso pode ser adquirido da API de gerenciamento de Mapas.

O Authorization URL é específico para a instância de nuvem pública do Azure. As nuvens soberanas têm URLs de autorização exclusivas e configurações de Microsoft Entra ID. * O controle de acesso baseado em função do Azure é configurado no plano de gerenciamento do Azure por meio de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST. * O uso do SDK da Web Azure Mapas permite a configuração baseada em configuração de um aplicativo para vários casos de uso.

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

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

Scopes

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

subscription-key

Essa é uma chave compartilhada provisionada ao criar um recurso Azure Mapas por meio do plano de gerenciamento do Azure por meio de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.

Com essa chave, qualquer aplicativo está autorizado a acessar todas as APIs REST. Em outras palavras, elas podem atualmente ser tratadas como master chaves para a conta para a qual são emitidas.

Para aplicativos expostos publicamente, nossa recomendação é usar o acesso de servidor a servidor de Azure Mapas APIs REST em que essa chave pode ser armazenada com segurança.

Type: apiKey
In: header

SAS Token

Esse é um token de assinatura de acesso compartilhado criado a partir da operação Listar SAS no recurso Azure Mapas por meio do plano de gerenciamento do Azure por meio de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST.

Com esse token, qualquer aplicativo está autorizado a acessar com controles de acesso baseados em função do Azure e controle refinado à expiração, taxa e regiões de uso para o token específico. Em outras palavras, o Token SAS pode ser usado para permitir que os aplicativos controlem o acesso de maneira mais segura do que a chave compartilhada.

Para aplicativos expostos publicamente, nossa recomendação é configurar uma lista específica de origens permitidas no recurso de conta do Mapa para limitar o abuso de renderização e renovar regularmente o Token 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

Nome	Description
ErrorAdditionalInfo	As informações adicionais do erro de gerenciamento de recursos.
ErrorDetail	O detalhe do erro.
ErrorResponse	Resposta de erro
LocalizedMapView	O parâmetro View (também chamado de parâmetro "região do usuário") permite mostrar os mapas corretos para um determinado país/região para regiões geopolíticas disputadas. Diferentes países/regiões têm diferentes exibições dessas regiões e o parâmetro View permite que seu aplicativo cumpra a exibição exigida pelo país/região que seu aplicativo atenderá. Por padrão, o parâmetro View é definido como "Unificado", mesmo que você não o tenha definido na solicitação. É sua responsabilidade determinar a localização de seus usuários e, em seguida, definir o parâmetro View corretamente para esse local. Como alternativa, você tem a opção de definir 'View=Auto', que retornará os dados do mapa com base no endereço IP da solicitação. O parâmetro View em Azure Mapas deve ser usado em conformidade com as leis aplicáveis, incluindo aquelas relativas ao mapeamento, do país/região em que são disponibilizados mapas, imagens e outros dados e conteúdo de terceiros que você está autorizado a acessar por meio de Azure Mapas. Exemplo: view=IN. Consulte Modos de exibição com suporte para obter detalhes e para ver as Exibições disponíveis.
MapImageStyle	Estilo de mapa a ser retornado. Os valores possíveis são main e escuros.
RasterTileFormat	Formato desejado da resposta. Valor possível: png.
StaticMapLayer	Camada de mapa solicitada. Se a camada for definida como rótulos ou híbrido, o formato deverá ser png.

ErrorAdditionalInfo

As informações adicionais do erro de gerenciamento de recursos.

Nome	Tipo	Description
info	object	As informações adicionais.
type	string	O tipo de informação adicional.

ErrorDetail

O detalhe do erro.

Nome	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 de erro

Nome	Tipo	Description
error	ErrorDetail	O objeto de erro.

LocalizedMapView

O parâmetro View (também chamado de parâmetro "região do usuário") permite mostrar os mapas corretos para um determinado país/região para regiões geopolíticas disputadas. Diferentes países/regiões têm diferentes exibições dessas regiões e o parâmetro View permite que seu aplicativo cumpra a exibição exigida pelo país/região que seu aplicativo atenderá. Por padrão, o parâmetro View é definido como "Unificado", mesmo que você não o tenha definido na solicitação. É sua responsabilidade determinar a localização de seus usuários e, em seguida, definir o parâmetro View corretamente para esse local. Como alternativa, você tem a opção de definir 'View=Auto', que retornará os dados do mapa com base no endereço IP da solicitação. O parâmetro View em Azure Mapas deve ser usado em conformidade com as leis aplicáveis, incluindo aquelas relativas ao mapeamento, do país/região em que são disponibilizados mapas, imagens e outros dados e conteúdo de terceiros que você está autorizado a acessar por meio de Azure Mapas. Exemplo: view=IN.

Consulte Modos de exibição com suporte para obter detalhes e para ver as Exibições disponíveis.

Nome	Tipo	Description
AE	string	Emirados Árabes Unidos (Exibição Árabe)
AR	string	Argentina (Exibição Argentina)
Auto	string	Retornar os dados do mapa com base no endereço IP da solicitação.
BH	string	Bahrein (Exibição Árabe)
IN	string	Índia (Exibição Indiana)
IQ	string	Iraque (Exibição Árabe)
JO	string	Jordânia (Exibição Árabe)
KW	string	Kuwait (Exibição Árabe)
LB	string	Líbano (Exibição Árabe)
MA	string	Marrocos (Exibição Marroquina)
OM	string	Omã (Exibição Árabe)
PK	string	Paquistão (Exibição Paquistanesa)
PS	string	Autoridade Palestina (Exibição Árabe)
QA	string	Qatar (Exibição Árabe)
SA	string	Arábia Saudita (Exibição Árabe)
SY	string	Síria (Exibição Árabe)
Unified	string	Exibição Unificada (Outras)
YE	string	Iêmen (Exibição Árabe)

MapImageStyle

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

Nome	Tipo	Description
dark	string	Versão cinza escuro do estilo Azure Mapas main
main	string	estilo Azure Mapas main

RasterTileFormat

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

Nome	Tipo	Description
png	string	Uma imagem no formato png. Dá suporte aos níveis de zoom de 0 a 18.

StaticMapLayer

Camada de mapa solicitada. Se a camada for definida como rótulos ou híbrido, o formato deverá ser png.

Nome	Tipo	Description
basic	string	Retorna uma imagem que contém todos os recursos do mapa, incluindo polígonos, bordas, estradas e rótulos.
hybrid	string	Retorna uma imagem que contém bordas, estradas e rótulos e pode ser sobreposta em outros blocos (como imagens de satélite) para produzir blocos híbridos.
labels	string	Retorna uma imagem apenas das informações de rótulo do mapa.