Criar conjunto de dados

A criação de um conjunto de dados é um processo de duas etapas:

  1. Faça uma solicitação para criar o conjunto de dados.

  2. Faça uma solicitação para fazer o upload de dados para o 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.

Requisitos de GeoJSON

A API Maps Datasets é compatível com a especificação atual do 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 desse tipo é um conjunto de objetos de elementos.

A API Maps Datasets não é compatível com arquivos GeoJSON que têm dados em um sistema de referência de coordenadas (CRS, na sigla em inglês) 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.
Os seguintes elementos KML não são compatíveis:
  • Í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 e long, elas poderão estar em qualquer ordem.

Resolver 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, ou type não é uma string. O arquivo de dados GeoJSON enviado precisa ter um campo de string chamado type 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 e y 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çalhos x e y. Se as unidades incorretas forem usadas, o conjunto poderá ser importado, mas os dados renderizados talvez mostrem os pontos em locais inesperados.

Fazer uma solicitação para criar o conjunto de dados

Crie um conjunto de dados enviando uma solicitação POST ao endpoint 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ê deve:

  • Especifique o displayName do conjunto de dados. O valor de displayName precisa ser exclusivo para todos os conjuntos de dados.

  • Defina usage como USAGE_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, com outras informações. Use o ID do conjunto de dados ao fazer solicitações para atualizar ou modificar o conjunto.

{
  "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 uma solicitação para fazer o upload de dados para o conjunto de dados

Depois de criar o conjunto, faça o upload dos dados do Google Cloud Storage 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 seu conjunto de dados, envie uma solicitação POST ao endpoint 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 formato gs://GCS_BUCKET/FILE.

    Para fazer a solicitação, o usuário precisa ter o papel Leitor de objetos do Storage ou qualquer outro papel que inclua a permissão storage.objects.get. 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 do arquivo dos dados como: FILE_FORMAT_GEOJSON (arquivo GeoJson), FILE_FORMAT_KML (arquivo KML) ou FILE_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 upload de dados de um arquivo, envie uma solicitação HTTP POST para o endpoint 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 está definido como multipart.

  • A propriedade metadata que especifica o caminho para um arquivo que especifica o tipo de dados para upload, como: FILE_FORMAT_GEOJSON (arquivo GeoJSON), FILE_FORMAT_KML (arquivo KML) ou FILE_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"
}