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 upload de dados para o conjunto de dados.

Após o upload inicial, você pode fazer upload de novos dados para criar uma nova versão do conjunto de dados.

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 para a solicitação que define o conjunto de dados. Você precisa:

  • 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 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 do Google Cloud Storage ou de um arquivo local para ele.

A operação de upload é assíncrona. Depois de fazer o upload, os dados são ingeridos e processados. Isso significa que você precisa fazer uma solicitação HTTP GET para monitorar o estado do conjunto de dados e determinar quando ele está pronto para uso ou se houve algum erro. Para mais informações, consulte Receber o estado do processamento de dados.

Fazer upload de dados do Cloud Storage

Para fazer upload do Cloud Storage para seu conjunto de dados, envie uma solicitação POST para o endpoint datasets que também inclua 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 de leitor de objetos do Storage ou outra função 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 o upload de dados de um arquivo, envie uma solicitação POST HTTP 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 a ser enviado, 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 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 de processamento de dados

A operação de upload é assíncrona. Isso significa que, após a chamada de API para fazer o upload dos dados para o conjunto de dados retornar, você precisa consultar o conjunto de dados para determinar se a transferência e o processamento de dados foram bem-sucedidos ou não.

Para determinar o state do conjunto de dados, use Pegar um conjunto de dados. Por exemplo, enquanto os dados estão sendo processados, o state é definido como STATE_PROCESSING. Quando o conjunto de dados estiver pronto para uso no 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 de STATE_COMPLETED, como STATE_PUBLISHING_FAILED ou qualquer status que termine na string _FAILED.

Por exemplo, você faz upload de dados para um conjunto de dados e, em seguida, faz uma solicitação GET para conferir os detalhes do conjunto de dados. Além da propriedade state, 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 única mensagem que descreve o erro. No entanto, uma única mensagem de erro não fornece necessariamente informações suficientes para identificar e corrigir os problemas.

Para ver informações completas do erro, chame a API fetchDatasetErrors. 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 do tipo Status por chamada e oferece suporte a 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, ou seja, mais de uma página de erros, a resposta conterá 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 anterior:

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. Use 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 fazer o upload dos dados iniciais com sucesso, o estado do conjunto de dados é definido como STATE_COMPLETED. Isso significa que o conjunto de dados está pronto para ser usado no app. Para determinar o state do conjunto de dados, consulte Receber um conjunto de dados.

Também é possível fazer o upload de novos dados para o conjunto de dados para criar uma nova versão dele. Para fazer upload de novos dados, use o mesmo processo usado para Fazer upload de dados do Cloud Storage ou Fazer upload de dados de um arquivo, e especifique os novos dados a serem enviados.

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 a versão "ativa" e é a versão usada pelo 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 bem-sucedida do conjunto de dados anterior permanece como a versão "ativa" e é a versão usada pelo app.