Migrar da API Find Time Zone do Bing Mapas

Este artigo explica como fazer a migração da API Find Time Zone do Bing Mapas para a API Get Timezone By Coordinates do Azure Mapas. A API Get Timezone By Coordinates do Azure Mapas retorna informações atuais, históricas e futuras de fuso horário para um par de latitude/longitude especificado, bem como horários do nascer e pôr do sol para uma determinada localização.

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 Find Time Zone do Bing Mapas dá suporte a coordenadas e nome da localização, região administrativa e nome do país/da região como entrada de localização. A API Get Timezone By Coordinates do Azure Mapas dá suporte somente a coordenadas. Para obter as coordenadas do nome da localização, da região administrativa e do nome do país/da região, use a API Get Geocoding do Azure Mapas.
A API Find Time Zone do Bing Mapas dá suporte a formatos de resposta XML e JSON, enquanto a API Get Timezone By Coordinates do Azure Mapas dá suporte apenas a JSON.
A API Find Time Zone do Bing Mapas não oferece valores de nascer e pôr do sol para um determinado fuso horário, ao contrário da API Get Time Zone By Coordinates do Azure Mapas.
Ao contrário do Bing Mapas para Empresas, o Azure Mapas é um serviço global que dá suporte à especificação de um escopo geográfico, o que permite limitar a residência de dados às áreas geográficas (geos) da Europa (UE) ou dos Estados Unidos (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 opções de autenticação de chamadas à API, como uma chave de assinatura, o Microsoft Entra ID ou o token SAS (assinatura de acesso compartilhado). Para obter mais informações sobre segurança e autenticação no Azure Mapas, consulte Autenticação com o Azure Mapas e a seção Segurança na documentação Obter fuso horário por coordenadas do Azure Mapas.

Parâmetros da solicitação

A seguinte tabela lista os parâmetros da solicitação Find Time Zone do Bing Mapas e o equivalente do Azure Mapas:

Parâmetro do Bing Mapas	Alias do parâmetro do Bing Mapas	Parâmetro do Azure Mapas	Obrigatório no Azure Mapas	Tipo de dados do Azure Mapas	Descrição
dateTime	dt	timeStamp	Falso	string date-time	Como alternativa, use o alias “stamp” ou “s”. Se a hora de referência for omitida, a API usará a hora do computador que atende à solicitação.
IncludeDstRules	Nenhuma	transitionsFrom	Falso	string date-time	A data de início na qual as transições de horário de verão são solicitadas só se aplica quando “options” = todas ou “options” = transições. Confira o parâmetro de opções (Timezone Options) para saber mais.
output	o	format	Verdadeiro	JSONFormat	Só há suporte ao formato JSON nesta API do Azure Mapas.
point	Nenhuma	consulta	Verdadeiro	número	Coordenadas do ponto para o qual as informações de fuso horário são solicitadas. Esse parâmetro é uma lista de coordenadas que contém um par de valores de coordenadas (latitude, longitude). Quando esse ponto de extremidade é chamado diretamente, as coordenadas são transmitidas como uma só cadeia de caracteres, contendo coordenadas separadas por vírgulas.
consulta	q	Sem suporte	Sem suporte	Sem suporte	Só há suporte para coordenadas do ponto para o qual as informações de fuso horário são solicitadas. Não há suporte para tipos de localização, como endereço, localidade, CEP etc. Para obter as coordenadas do nome da localização, da região administrativa e do nome do país/da região, use a API Get Geocoding do Azure Mapas.

Para saber mais, confira os parâmetros de URI da API Get Timezone By Coordinates do Azure Mapas.

Exemplos de solicitação

Solicitação da API Find Time Zone do Bing Mapas:

https://dev.virtualearth.net/REST/v1/timezone/37.7800,-122.4201?key=%7bBingMapsKey%7d

Solicitação da API Get Time Zone by Coordinates do Azure Mapas:

https://atlas.microsoft.com/timezone/byCoordinates/json?api-version=1.0&query=37.7800,-122.4201&subscription-key={Your-Azure-Maps-Subscription-key}

Campos de resposta

A seguinte tabela lista os campos que podem aparecer na resposta HTTP durante a execução da API Find Time Zone do Bing Mapas e o equivalente do Azure Mapas:

Campo de resposta do Bing Mapas	Campo de resposta do Azure Mapas
abbreviation (JSON) Abbreviation (XML)	ReferenceTime (Tag)
convertedTime (JSON) ConvertedTime (XML)	ReferenceTime (WallTime)
dstRule (JSON) DSTRule (XML)	TimeTransitions
genericName (JSON) GenericName (XML)	TimezoneNames
ianaTimeZoneId (JSON) IANATimeZoneID (XML)	ID
utcOffset (JSON) UTCOffset (XML)	ReferenceTime (StandardOffset)
windowsTimeZoneID (JSON) WindowsTimeZoneID (XML)	Sem suporte. Use a API Get Timezone Enum Windows do Azure Mapas para conversão no fuso horário do Windows.

Para saber mais sobre os campos de resposta da API Get Timezone By Coordinates do Azure Mapas, confira as Definições de resposta.

Exemplos de respostas

O seguinte JSON traz uma amostra do que é retornado no corpo da resposta HTTP quando a solicitação da API Find Time Zone do Bing Mapas é executada:

{
    "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": "RESTTimeZone:http://schemas.microsoft.com/search/local/ws/rest/v1",
                    "timeZone": {
                        "genericName": "Pacific Standard Time",
                        "abbreviation": "PST",
                        "ianaTimeZoneId": "America/Los_Angeles",
                        "windowsTimeZoneId": "Pacific Standard Time",
                        "utcOffset": "-8:00",
                        "convertedTime": {
                            "localTime": "2024-02-11T14:21:58",
                            "utcOffsetWithDst": "-8:00",
                            "timeZoneDisplayName": "Pacific Standard Time",
                            "timeZoneDisplayAbbr": "PST"
                        }
                    }
                }
            ]
        }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "f02637665942c8cb21c8414bd03224aa|MWH0032BEF|0.0.0.1"
}

O seguinte exemplo mostra o que é retornado no corpo da resposta HTTP quando uma solicitação da API Get Time Zone By Coordinates do Azure Mapas é executada:

{
    "Version": "2023d",
    "ReferenceUtcTimestamp": "2024-02-11T22:32:29.4282815Z",
    "TimeZones": [
        {
            "Id": "America/Los_Angeles",
            "Aliases": [
                "US/Pacific"
            ],
            "Countries": [
                {
                    "Name": "United States",
                    "Code": "US"
                }
            ],
            "Names": {
                "ISO6391LanguageCode": "en",
                "Generic": "Pacific Time",
                "Standard": "Pacific Standard Time",
                "Daylight": "Pacific Daylight Time"
            },
            "ReferenceTime": {
                "Tag": "PST",
                "StandardOffset": "-08:00:00",
                "DaylightSavings": "00:00:00",
                "WallTime": "2024-02-11T14:32:29.4282815-08:00",
                "PosixTzValidYear": 2024,
                "PosixTz": "PST+8PDT,M3.2.0,M11.1.0",
                "Sunrise": "2024-02-11T07:04:33.6950704-08:00",
                "Sunset": "2024-02-11T17:43:15.3679015-08:00"
            },
            "RepresentativePoint": {
                "Latitude": 34.05222222222222,
                "Longitude": -118.24277777777777
            },
            "TimeTransitions": [
                {
                    "Tag": "PST",
                    "StandardOffset": "-08:00:00",
                    "DaylightSavings": "00:00:00",
                    "UtcStart": "2023-11-05T09:00:00Z",
                    "UtcEnd": "2024-03-10T10:00:00Z"
                },
                {
                    "Tag": "PDT",
                    "StandardOffset": "-08:00:00",
                    "DaylightSavings": "01:00:00",
                    "UtcStart": "2024-03-10T10:00:00Z",
                    "UtcEnd": "2024-11-03T09:00:00Z"
                },
                {
                    "Tag": "PST",
                    "StandardOffset": "-08:00:00",
                    "DaylightSavings": "00:00:00",
                    "UtcStart": "2024-11-03T09:00:00Z",
                    "UtcEnd": "2025-03-09T10:00:00Z"
                }
            ]
        }
    ]
}

Uso de transações

Semelhante à API Find Time Zone do Bing Mapas para Empresas, a API Get Timezone By Coordinates do Azure Mapas registra uma transação de cobrança por solicitação de API. Para obter mais informações sobre as transações do Azure Mapas, confira Noções básicas sobre transações do Azure Mapas.

Informações adicionais

Mais APIs Timezone do Azure Mapas

Suporte

Fórum do Microsoft Q&A

Comentários

Esta página foi útil?

Last updated on 2024-05-28