A criação de um conjunto de dados é um processo de duas etapas:
Faça uma solicitação para criar o conjunto de dados.
Faça uma solicitação para fazer upload de dados no conjunto.
Após o upload inicial dos dados, você pode carregar novos dados para o conjunto de dados para criar uma nova versão do conjunto de dados.
Pré-requisitos
Ao criar um conjunto de dados:
- Os nomes de exibição precisam ser exclusivos no projeto do Google Cloud.
- Esses nomes devem ter menos de 64 bytes. Como os caracteres são representados em UTF-8, em alguns idiomas, um caractere pode ser representado por vários bytes.
- As descrições precisam ter menos de 1.000 bytes.
Ao fazer o upload de dados:
- Os tipos de arquivos compatíveis são CSV, GeoJSON e KML.
- O tamanho máximo de arquivo permitido é 350 MB.
- Os nomes das colunas de atributos não podem começar com a string "?_".
- Geometrias tridimensionais não são aceitas. Isso inclui o sufixo "Z" no formato WKT e a coordenada de altitude no formato GeoJSON.
Práticas recomendadas para a preparação de dados
Se os dados de origem forem complexos ou grandes, como pontos densos, linhas de linha longas ou polígonos (geralmente arquivos com mais de 50 MB se enquadram nessa categoria), simplifique os dados. antes de fazer o upload para obter o melhor desempenho em um mapa visual.
Confira algumas práticas recomendadas para preparar os dados:
- Minimize as propriedades de recursos. Manter apenas as propriedades de elementos necessárias para definir o estilo seu mapa, por exemplo, "id" e "category". É possível mesclar propriedades adicionais a um recurso em um cliente aplicativo usando estilos baseados em dados em uma chave de identificador exclusivo. Por exemplo, consulte Veja seus dados em tempo real com o estilo baseado em dados.
- Use tipos de dados simples para objetos de propriedade sempre que possível, como números inteiros, para minimizar o tamanho do bloco e melhorar o desempenho do mapa.
- Simplifique geometrias complexas antes de fazer o upload de um arquivo. Você pode fazer isso em uma ferramenta geoespacial de sua preferência, como utilitário Mapshaper.org ou no BigQuery usando ST_Simplify em geometrias de polígono complexas.
- Pontos muito densos do cluster antes do upload de um arquivo. Você pode fazer isso em uma ferramenta geoespacial de sua preferência, como funções de cluster turf.js ou no BigQuery usando ST_CLUSTERDBSCAN em geometrias de pontos densas.
Confira mais orientações sobre as práticas recomendadas para conjuntos de dados em Visualize seus dados com conjuntos de dados e o BigQuery.
Requisitos de GeoJSON
A API Maps Datasets é compatível com a especificação GeoJSON (link em inglês) A API Maps Datasets também aceita arquivos GeoJSON que contêm qualquer um destes tipos de objetos:
- Objetos de geometria. Esse tipo de objeto é uma forma espacial, descrita como uma união de pontos, linhas e polígonos com furos opcionais.
- Objetos de elementos. Esse tipo de objeto contém uma geometria e outros pares de nome/valor, com um significado específico do aplicativo.
- Coleções de elementos. Uma coleção de recursos é um conjunto de objetos de recursos.
A API Maps Datasets não é compatível com arquivos GeoJSON que têm dados em um sistema de referência de coordenadas (CRS) diferente de WGS84.
Para mais informações sobre o GeoJSON, consulte Compliance com RFC 7946 (ambos os links em inglês).
Requisitos de KML
A API Maps Datasets tem os seguintes requisitos:
- Todos os URLs precisam ser locais (ou relativos) ao próprio arquivo.
- Compatível com geometrias de ponto, linha e polígono.
- Todos os atributos de dados são considerados strings.
- Ícones ou
<styleUrl>
definidos fora do arquivo - Links de rede, como
<NetworkLink>
- Sobreposições de solo, por exemplo,
<GroundOverlay>
- Geometrias 3D ou qualquer tag relacionada à altitude, como
<altitudeMode>
- Especificações da câmera, por exemplo,
<LookAt>
- Estilos definidos dentro do arquivo KML
Requisitos de CSV
Para arquivos CSV, os nomes das colunas compatíveis são listados abaixo em ordem de prioridade:
latitude
,longitude
lat
,long
x
,y
wkt
(texto conhecido)address
,city
,state
,zip
address
- Uma única coluna contendo todas as informações de endereço, como
1600 Amphitheatre Parkway Mountain View, CA 94043
Por exemplo, seu arquivo inclui colunas chamadas x
, y
e wkt
.
Como x
e y
têm uma prioridade mais alta, segundo a ordem dos nomes de colunas compatíveis na lista acima, os valores nas colunas x
e y
são usados, e a coluna wkt
é ignorada.
Além disso:
- Cada nome de coluna tem que pertencer a uma única coluna, ou seja, não é possível ter uma coluna chamada
xy
que inclua dados das coordenadas x e y. Essas coordenadas precisam estar em colunas diferentes. - Os nomes das colunas não diferenciam maiúsculas de minúsculas.
- A ordem dos nomes não importa. Por exemplo, se o arquivo CSV tiver colunas
lat
elong
, elas poderão estar em qualquer ordem.
Solucionar erros de upload de dados
Ao fazer o upload de dados para um conjunto, você pode encontrar um dos erros comuns descritos nesta seção.
Erros de GeoJSON
Exemplo de erro comum de GeoJSON:
- Campo
type
faltando, outype
não é uma string. O arquivo de dados GeoJSON enviado precisa ter um campo de string chamadotype
em cada definição de objeto de elemento e de geometria.
Erros de KML
Exemplo de erro comum de KML:
- O arquivo de dados não pode conter nenhum dos elementos KML incompatíveis listados acima. Caso contrário, a importação pode falhar.
Erros de CSV
Exemplos de erros comuns de CSV:
- Algumas linhas não contêm valores para uma coluna de geometria. Em um arquivo CSV, todas as linhas em colunas desse tipo precisam ter valores não vazios. Confira algumas colunas de geometria:
latitude
,longitude
lat
,long
x
,y
wkt
address
,city
,state
,zip
address
- Uma única coluna contendo todas as informações de endereço, como
1600 Amphitheatre Parkway Mountain View, CA 94043
- Se
x
ey
forem suas colunas de geometria, verifique se as unidades são longitude e latitude. Alguns conjuntos de dados públicos usam sistemas de coordenadas diferentes nos cabeçalhosx
ey
. Se as unidades incorretas forem usadas, o conjunto poderá ser importado, mas os dados renderizados talvez mostrem os pontos em locais inesperados.
Crie o conjunto de dados
Crie um conjunto de dados enviando uma solicitação POST
ao
datasets:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
Transmita um corpo JSON. à solicitação que define o conjunto de dados. Você precisa:
Especifique o
displayName
do conjunto de dados. O valor dedisplayName
precisa ser exclusivo para todos os conjuntos de dados.Defina
usage
comoUSAGE_DATA_DRIVEN_STYLING
.
Exemplo:
curl -X POST -d '{ "displayName": "My Test Dataset", "usage": "USAGE_DATA_DRIVEN_STYLING" }' \ -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $TOKEN" \ https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets
A resposta contém o ID do conjunto de dados, no formato
projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID
além de informações adicionais. Use o ID do conjunto de dados ao fazer solicitações para
para atualizar ou modificar o conjunto de dados.
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46", "displayName": "My Test Dataset", "usage": [ "USAGE_DATA_DRIVEN_STYLING" ], "createTime": "2022-08-15T17:50:00.189682Z", "updateTime": "2022-08-15T17:50:00.189682Z" }
Fazer upload de dados para o conjunto de dados
Depois de criar o conjunto de dados, faça o upload dos dados Google Cloud Storage (em inglês) ou de um arquivo local para o conjunto de dados.
Fazer upload de dados do Cloud Storage
Para fazer o upload do Cloud Storage para o conjunto de dados, envie uma solicitação POST
para o
datasets que também
inclui o ID do conjunto de dados:
https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
No corpo da solicitação JSON:
Use
inputUri
para especificar o caminho do arquivo para o recurso que contém os dados no Cloud Storage. Esse caminho está no formatogs://GCS_BUCKET/FILE
:Para fazer a solicitação, o usuário precisa do objeto do Storage Leitor papel ou qualquer outro que inclua a permissão
storage.objects.get
. Para para mais informações sobre como gerenciar o acesso ao Cloud Storage, consulte Visão geral do controle de acesso.Use
fileFormat
para especificar o formato de arquivo dos dados como:FILE_FORMAT_GEOJSON
(arquivo GeoJson),FILE_FORMAT_KML
(arquivo KML) ouFILE_FORMAT_CSV
(arquivo CSV).
Exemplo:
curl -X POST -d '{ "gcs_source":{ "inputUri": "gs://my_bucket/my_csv_file", "fileFormat": "FILE_FORMAT_CSV" } }' \ -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \ -H "content-type: application/json" \ -H "Authorization: Bearer $TOKEN" \ https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import
A resposta está no formato:
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
Fazer upload de dados de um arquivo
Para fazer o upload de dados a partir de um arquivo, envie uma solicitação POST
HTTP para o
datasets que também
inclui o ID do conjunto de dados:
https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID:import
A solicitação contém:
O cabeçalho
Goog-Upload-Protocol
é definido comomultipart
.A propriedade
metadata
especificando o caminho para um arquivo que especifica o tipos de dados para fazer upload, como:FILE_FORMAT_GEOJSON
(arquivo GeoJSON),FILE_FORMAT_KML
(arquivo KML) ouFILE_FORMAT_CSV
(arquivo CSV).O conteúdo desse arquivo tem o seguinte formato:
{"local_file_source": {"file_format": "FILE_FORMAT_GEOJSON"}}
A propriedade
rawdata
que especifica o caminho para o arquivo GeoJSON, KML ou CSV que contêm os dados para upload.
A solicitação a seguir usa a opção curl -F
para especificar o caminho para os dois
arquivos:
curl -X POST \ -H 'X-Goog-User-Project: PROJECT_NUMBER_OR_ID' \ -H "Authorization: Bearer $TOKEN" \ -H "X-Goog-Upload-Protocol: multipart" \ -F "metadata=@csv_metadata_file" \ -F "rawdata=@csv_data_file" \ https://mapsplatformdatasets.googleapis.com/upload/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:import
A resposta está no formato:
{ "name": "projects/PROJECT_NUMBER_OR_ID/datasets/DATASET_ID@VERSION_NUMBER" }
Fazer upload de novos dados para o conjunto de dados
Depois de criar o conjunto de dados e carregar os dados iniciais com sucesso, o estado
do conjunto de dados é definido como STATE_COMPLETED
. Isso significa que o conjunto de dados está pronto
usar no seu app. Para determinar o state
do conjunto de dados, consulte Receber um
no conjunto de dados.
Você também pode carregar novos dados para o conjunto de dados para criar uma nova versão do no conjunto de dados. Para fazer o upload de novos dados, siga o mesmo processo usado para Fazer upload de dados do Cloud Storage ou fazer upload de dados de um arquivo, e especificar os novos dados para upload.
Se o upload dos novos dados for concluído:
O estado da nova versão do conjunto de dados é definido como
STATE_COMPLETED
.A nova versão se torna "ativa" e é a versão usada pelo seu app.
Se houver um erro no upload:
O estado da nova versão do conjunto de dados é definido como um dos seguintes estados:
STATE_IMPORT_FAILED
STATE_PROCESSING_FAILED
STATE_PUBLISHING_FAILED
STATE_DELETION_FAILED
A versão anterior do conjunto de dados bem-sucedida permanece como "ativa" versão e é a versão usada pelo seu app.