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 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.

Criar 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 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 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.

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 formato gs://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) 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 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 como multipart.

  • 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) 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"
}

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.