Dados de localização Geospatial e GeoJSON em Azure Cosmos DBGeospatial and GeoJSON location data in Azure Cosmos DB

Este artigo é uma introdução à funcionalidade geoespacial em Azure Cosmos DB.This article is an introduction to the geospatial functionality in Azure Cosmos DB. Atualmente, armazenar e aceder a dados geoespaciais é suportado apenas pelas contas Azure Cosmos DB SQL API.Currently storing and accessing geospatial data is supported by Azure Cosmos DB SQL API accounts only. Depois de ler a nossa documentação sobre a indexação geoespacial, poderá responder às seguintes perguntas:After reading our documentation on geospatial indexing you will be able to answer the following questions:

  • Como posso armazenar dados espaciais em Azure Cosmos DB?How do I store spatial data in Azure Cosmos DB?
  • Como posso consultar dados geoespaciais em Azure Cosmos DB em SQL e LINQ?How can I query geospatial data in Azure Cosmos DB in SQL and LINQ?
  • Como posso ativar ou desativar a indexação espacial em Azure Cosmos DB?How do I enable or disable spatial indexing in Azure Cosmos DB?

Casos de utilização de dados espaciaisSpatial Data Use Cases

Os dados geoespacial envolvem muitas vezes consultas de proximidade, por exemplo, "encontrar todos os cafés perto da minha localização atual".Geospatial data often involve proximity queries, for example, "find all coffee shops near my current location". Os casos de uso comum são:Common use cases are:

  • Geolocalização Analytics, impulsionando iniciativas específicas de marketing localizadas.Geolocation Analytics, driving specific located marketing initiatives.
  • Personalização baseada em localização, para várias indústrias como o Retail and Healthcare.Location based personalization, for multiple industries like Retail and Healthcare.
  • Melhoria logística, para otimização de transportes.Logistics enhancement, for transport optimization.
  • Análise de Risco, especialmente para empresas de seguros e finanças.Risk Analysis, especially for insurance and finance companies.
  • Sensibilização para a situação, para alertas e notificações.Situational awareness, for alerts and notifications.

Introdução aos dados espaciaisIntroduction to spatial data

Os dados espaciais descrevem a posição e a forma dos objetos no espaço.Spatial data describes the position and shape of objects in space. Na maioria das aplicações, estas correspondem a objetos na terra e dados geoespacial.In most applications, these correspond to objects on the earth and geospatial data. Dados espaciais podem ser usados para representar a localização de uma pessoa, um lugar de interesse, ou o limite de uma cidade, ou um lago.Spatial data can be used to represent the location of a person, a place of interest, or the boundary of a city, or a lake.

A AZure Cosmos DB's SQL API suporta dois tipos de dados espaciais: o tipo de dados de geometria e o tipo de dados de geografia.Azure Cosmos DB's SQL API supports two spatial data types: the geometry data type and the geography data type.

  • O tipo de geometria representa dados num sistema de coordenadas euclidídeos (plano)The geometry type represents data in a Euclidean (flat) coordinate system
  • O tipo de geografia representa dados num sistema de coordenadas de terra redonda.The geography type represents data in a round-earth coordinate system.

Tipos de dados suportadosSupported data types

O Azure Cosmos DB suporta a indexação e consulta de dados de pontos geoespaciais que são representados usando a especificação GeoJSON.Azure Cosmos DB supports indexing and querying of geospatial point data that's represented using the GeoJSON specification. As estruturas de dados da GeoJSON são sempre objetos JSON válidos, para que possam ser armazenados e consultados utilizando o Azure Cosmos DB sem ferramentas ou bibliotecas especializadas.GeoJSON data structures are always valid JSON objects, so they can be stored and queried using Azure Cosmos DB without any specialized tools or libraries.

A Azure Cosmos DB suporta os seguintes tipos de dados espaciais:Azure Cosmos DB supports the following spatial data types:

  • PontoPoint
  • LineStringLineString
  • PolígonoPolygon
  • MultiPolygonMultiPolygon

PontosPoints

Um ponto denota uma única posição no espaço.A Point denotes a single position in space. Em dados geoespaciais, um Ponto representa a localização exata, que pode ser um endereço de rua de uma mercearia, um quiosque, um automóvel, ou uma cidade.In geospatial data, a Point represents the exact location, which could be a street address of a grocery store, a kiosk, an automobile, or a city. Um ponto é representado em GeoJSON (e Azure Cosmos DB) usando o seu par de coordenadas ou longitude e latitude.A point is represented in GeoJSON (and Azure Cosmos DB) using its coordinate pair or longitude and latitude.

Aqui está um exemplo JSON para um ponto:Here's an example JSON for a point:

Pontos em Azure Cosmos DBPoints in Azure Cosmos DB

{
    "type":"Point",
    "coordinates":[ 31.9, -4.8 ]
}

Os tipos de dados espaciais podem ser incorporados num documento DB da Azure Cosmos, como mostra este exemplo de um perfil de utilizador que contém dados de localização:Spatial data types can be embedded in an Azure Cosmos DB document as shown in this example of a user profile containing location data:

Use o perfil com localização armazenada em Azure Cosmos DBUse Profile with Location stored in Azure Cosmos DB

{
    "id":"cosmosdb-profile",
    "screen_name":"@CosmosDB",
    "city":"Redmond",
    "topics":[ "global", "distributed" ],
    "location":{
        "type":"Point",
        "coordinates":[ 31.9, -4.8 ]
    }
}

Pontos num sistema de coordenadas de geometriaPoints in a geometry coordinate system

Para o tipo de dados de geometria, a especificação geoJSON especifica primeiro o eixo horizontal e o eixo vertical em segundo.For the geometry data type, GeoJSON specification specifies the horizontal axis first and the vertical axis second.

Pontos num sistema de coordenadas de geografiaPoints in a geography coordinate system

Para o tipo de dados de geografia, a especificação geoJSON especifica a longitude em primeiro lugar e a latitude em segundo lugar.For the geography data type, GeoJSON specification specifies longitude first and latitude second. Como em outras aplicações de mapeamento, a longitude e a latitude são ângulos e representados em termos de graus.Like in other mapping applications, longitude and latitude are angles and represented in terms of degrees. Os valores de longitude são medidos a partir do Primeiro Meridiano e estão entre -180 graus e 180,0 graus, e os valores de latitude são medidos a partir do equador e estão entre -90,0 graus e 90,0 graus.Longitude values are measured from the Prime Meridian and are between -180 degrees and 180.0 degrees, and latitude values are measured from the equator and are between -90.0 degrees and 90.0 degrees.

AZure Cosmos DB interpreta as coordenadas representadas pelo sistema de referência WGS-84.Azure Cosmos DB interprets coordinates as represented per the WGS-84 reference system. Veja abaixo mais detalhes sobre os sistemas de referência de coordenadas.See below for more details about coordinate reference systems.

LineStringsLineStrings

Os LineStrings representam uma série de dois ou mais pontos no espaço e os segmentos de linha que os ligam.LineStrings represent a series of two or more points in space and the line segments that connect them. Em dados geoespaciais, os LineStrings são comumente usados para representar autoestradas ou rios.In geospatial data, LineStrings are commonly used to represent highways or rivers.

LineStrings em GeoJSONLineStrings in GeoJSON

    "type":"LineString",
    "coordinates":[ [
        [ 31.8, -5 ],
        [ 31.8, -4.7 ]
    ] ]

PolígonosPolygons

Um Polígono é um limite de pontos conectados que forma um LineString fechado.A Polygon is a boundary of connected points that forms a closed LineString. Os polígonos são comumente usados para representar formações naturais como lagos ou jurisdições políticas como cidades e estados.Polygons are commonly used to represent natural formations like lakes or political jurisdictions like cities and states. Aqui está um exemplo de um Polígono em Azure Cosmos DB:Here's an example of a Polygon in Azure Cosmos DB:

Polígonos em GeoJSONPolygons in GeoJSON

{
    "type":"Polygon",
    "coordinates":[ [
        [ 31.8, -5 ],
        [ 31.8, -4.7 ],
        [ 32, -4.7 ],
        [ 32, -5 ],
        [ 31.8, -5 ]
    ] ]
}

Nota

A especificação GeoJSON requer que, para polígonos válidos, o último par de coordenadas fornecido deve ser o mesmo que o primeiro, para criar uma forma fechada.The GeoJSON specification requires that for valid Polygons, the last coordinate pair provided should be the same as the first, to create a closed shape.

Os pontos dentro de um polígono devem ser especificados em ordem no sentido contrário ao dos ponteiros do relógio.Points within a Polygon must be specified in counter-clockwise order. Um polígono especificado na ordem do relógio representa o inverso da região dentro dela.A Polygon specified in clockwise order represents the inverse of the region within it.

MultiPolygonsMultiPolygons

Um MultiPolygon é uma matriz de zero ou mais Polígonos.A MultiPolygon is an array of zero or more Polygons. Os MultiPolygons não podem sobrepor-se a lados ou ter qualquer área comum.MultiPolygons cannot overlap sides or have any common area. Podem tocar em um ou mais pontos.They may touch at one or more points.

MultiPolygons em GeoJSONMultiPolygons in GeoJSON

{
    "type":"MultiPolygon",
    "coordinates":[[[
        [52.0, 12.0],
        [53.0, 12.0],
        [53.0, 13.0],
        [52.0, 13.0],
        [52.0, 12.0]
        ]],
        [[
        [50.0, 0.0],
        [51.0, 0.0],
        [51.0, 5.0],
        [50.0, 5.0],
        [50.0, 0.0]
        ]]]
}

Coordenar sistemas de referênciaCoordinate reference systems

Uma vez que a forma da terra é irregular, as coordenadas de dados geoespaciais de geografia estão representadas em muitos sistemas de referência de coordenadas (SIR), cada um com os seus próprios quadros de referência e unidades de medição.Since the shape of the earth is irregular, coordinates of geography geospatial data are represented in many coordinate reference systems (CRS), each with their own frames of reference and units of measurement. Por exemplo, a "Rede Nacional da Grã-Bretanha" é um sistema de referência que é preciso para o Reino Unido, mas não fora dele.For example, the "National Grid of Britain" is a reference system is accurate for the United Kingdom, but not outside it.

O CRS mais popular em uso hoje é o World Geodetic System WGS-84.The most popular CRS in use today is the World Geodetic System WGS-84. Dispositivos GPS, e muitos serviços de mapeamento, incluindo Google Maps e Bing Maps APIs usam WGS-84.GPS devices, and many mapping services including Google Maps and Bing Maps APIs use WGS-84. O Azure Cosmos DB suporta a indexação e consulta de dados geoespaciais de geografia utilizando apenas o CRS WGS-84.Azure Cosmos DB supports indexing and querying of geography geospatial data using the WGS-84 CRS only.

Criação de documentos com dados espaciaisCreating documents with spatial data

Quando cria documentos que contenham valores GeoJSON, são automaticamente indexados a um índice espacial de acordo com a política de indexação do recipiente.When you create documents that contain GeoJSON values, they are automatically indexed with a spatial index in accordance to the indexing policy of the container. Se estiver a trabalhar com um Azure Cosmos DB SDK numa linguagem dinâmica como Python ou Node.js, deve criar um GeoJSON válido.If you're working with an Azure Cosmos DB SDK in a dynamically typed language like Python or Node.js, you must create valid GeoJSON.

Criar Documento com dados Geoespaciais em Node.jsCreate Document with Geospatial data in Node.js

var userProfileDocument = {
    "id":"cosmosdb",
    "location":{
        "type":"Point",
        "coordinates":[ -122.12, 47.66 ]
    }
};

client.createDocument(`dbs/${databaseName}/colls/${collectionName}`, userProfileDocument, (err, created) => {
    // additional code within the callback
});

Se estiver a trabalhar com as APIs SQL, pode utilizar o Point , e as classes dentro do espaço de LineString Polygon MultiPolygon Microsoft.Azure.Cosmos.Spatial nomes para incorporar informações de localização dentro dos objetos da sua aplicação.If you're working with the SQL APIs, you can use the Point, LineString, Polygon, and MultiPolygon classes within the Microsoft.Azure.Cosmos.Spatial namespace to embed location information within your application objects. Estas aulas ajudam a simplificar a serialização e a desseialização dos dados espaciais em GeoJSON.These classes help simplify the serialization and deserialization of spatial data into GeoJSON.

Criar Documento com dados Geoespaciais em .NETCreate Document with Geospatial data in .NET

using Microsoft.Azure.Cosmos.Spatial;

public class UserProfile
{
    [JsonProperty("id")]
    public string id { get; set; }

    [JsonProperty("location")]
    public Point Location { get; set; }

    // More properties
}

await container.CreateItemAsync( new UserProfile
    {
        id = "cosmosdb",
        Location = new Point (-122.12, 47.66)
    });

Se você não tem a informação de latitude e longitude, mas tem os endereços físicos ou nome de localização como cidade ou país/região, você pode procurar as coordenadas reais usando um serviço de geocoding como Bing Maps REST Services.If you don't have the latitude and longitude information, but have the physical addresses or location name like city or country/region, you can look up the actual coordinates by using a geocoding service like Bing Maps REST Services. Saiba mais sobre a geocodagem Bing Maps aqui.Learn more about Bing Maps geocoding here.

Próximos passosNext steps

Agora que aprendeu a começar com o suporte geoespacial em Azure Cosmos DB, a seguir pode:Now that you have learned how to get started with geospatial support in Azure Cosmos DB, next you can: