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.
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 upload dos dados Google Cloud Storage (em inglês) ou de um arquivo local para o conjunto de dados.
A operação de upload é assíncrona. Depois de fazer o upload dos dados, eles são ingeridos e processados. Isso significa que você deve fazer uma solicitação HTTP GET para monitorar o estado do conjunto de dados para determinar quando o conjunto de dados está pronto para uso ou se não houve erros. Para mais informações, consulte Adquirir o processamento de dados estado.
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 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
está 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" }
Acessar estado do processamento de dados
A operação de upload é assíncrona. Isso significa que, depois da chamada de API para fazer upload os dados para o conjunto de dados retorna, você deve pesquisar o conjunto de dados para determinar se a ingestão e o processamento de dados falharam.
Para determinar o state
do
conjunto de dados, use Receber um conjunto de dados. Por exemplo, enquanto os dados estão sendo
processado, o state
será definido como STATE_PROCESSING
. Quando o conjunto de dados estiver pronto
para usar no seu app, o state
será definido como STATE_COMPLETED
.
Por exemplo, faça uma chamada GET no conjunto de dados:
curl -X GET \ -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \ -H "Authorization: Bearer $TOKEN" \ "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46"
Para um upload bem-sucedido, o state
do conjunto de dados é STATE_COMPLETED
:
{ "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46", "displayName": "My Test Dataset", "description": " ", "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218", "usage": [ "USAGE_DATA_DRIVEN_STYLING" ], "localFileSource": { "filename": "Parks_Properties_20240529.csv", "fileFormat": "FILE_FORMAT_CSV" }, "createTime": "2024-05-30T16:41:11.130816Z", "updateTime": "2024-05-30T16:41:14.416130Z", "versionCreateTime": "2024-05-30T16:41:14.416130Z", "status": { "state": "STATE_COMPLETED", }, "sizeBytes": "6916924", "downloadable": true }
Quando o processamento de dados falha, state
é definido como um valor diferente
STATE_COMPLETED
, como STATE_PUBLISHING_FAILED
ou qualquer status que termine em
string _FAILED
.
Por exemplo, você carrega os dados em um conjunto de dados e depois faz um GET
para obter os detalhes do conjunto de dados. Junto com a propriedade state
, os
a resposta também inclui uma única propriedade errorMessage
que contém uma descrição
do erro.
{ "name": "projects/119757857/datasets/f57074a0-a8b6-403e-9df1-e9fc46", "displayName": "My Test Dataset", "description": " ", "versionId": "837c5a9e-c885-4a5f-a462-7e35673e5218", "usage": [ "USAGE_DATA_DRIVEN_STYLING" ], "localFileSource": { "filename": "Parks_Properties_20240529.csv", "fileFormat": "FILE_FORMAT_CSV" }, "createTime": "2024-05-30T16:41:11.130816Z", "updateTime": "2024-05-30T16:41:14.416130Z", "versionCreateTime": "2024-05-30T16:41:14.416130Z", "status": { "state": "STATE_PUBLISHING_FAILED", "errorMessage": "INVALID_ARGUMENT: Skipping row because address could not be geocoded: 5521 18 AVENUE (from line 79)" }, "sizeBytes": "6916924", "downloadable": true }
Receber erros de processamento de dados
Quando a ingestão e o processamento de dados falham, a propriedade errorMessage
contém uma
uma única mensagem descrevendo o erro. No entanto, uma única mensagem de erro
fornecer necessariamente informações suficientes para identificar e corrigir os problemas.
Para obter informações completas do erro, chame o método
fetchDatasetErrors
API. Essa API retorna todos os erros de processamento de dados associados a um conjunto de dados:
curl -X GET \ -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \ -H "Authorization: Bearer $TOKEN" \ "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors"
A resposta contém a matriz errors
. Essa matriz contém até 50 erros de
tipo Status
por chamada e suporta até 500 erros no total:
{ "nextPageToken": "cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj", "errors": [ { "code": 3, "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 631)" }, { "code": 3, "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 457)" }, { "code": 3, "message": "INVALID_ARGUMENT: No address was derived from fields 2. (from line 31)" }, ... ] }
Se houver mais de 50 erros, o que significa mais de uma página de
a resposta incluirá um token de página no campo nextPageToken
.
Transmita esse valor no parâmetro de consulta pageToken
de uma chamada subsequente para receber
a próxima página de erros. Quando nextPageToken
está vazio, não há mais páginas.
Por exemplo, para receber a próxima página de erros usando o token da resposta:
curl -X GET \ -H "content-type: application/json" \ -H "X-Goog-User-Project: PROJECT_NUMBER_OR_ID" \ -H "Authorization: Bearer $TOKEN" \ "https://mapsplatformdatasets.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID/datasets/f57074a0-a8b6-403e-9df1-e9fc46:fetchDatasetErrors?pageToken=cigKJkIkMTU3MzM0NjQtYzlmMy00YzYxLWIxM2YtYmVkYjFjYjRkYzRj"
Por padrão, a resposta contém no máximo 50 erros por página. Usar
O parâmetro de consulta pageSize
para controlar o tamanho da página.
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.