O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar conjunto de dados

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

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

Criar o conjunto de dados

Crie um conjunto de dados enviando uma solicitação POST para o endpoint de conjuntos de dados:

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

Observação: USAGE_DATA_DRIVEN_STYLING é o único valor compatível com usage.

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 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 de Google Cloud Storage 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ê precisa fazer uma solicitação GET para monitorar o estado do conjunto de dados e determinar quando ele está pronto para uso ou se houve erros. Para mais informações, consulte Receber o estado de processamento de dados.

Fazer upload de dados do Cloud Storage

Para fazer upload do Cloud Storage para o conjunto de dados, envie uma POST solicitação para o conjuntos de dados endpoint 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.

O usuário que faz a solicitação precisa da função Leitor de objetos do Storage ou de qualquer 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 de 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 de conjuntos de dados que também inclua 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 serem enviados, 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 a serem enviados.

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

Receber o estado de processamento de dados

A operação de upload é assíncrona. Isso significa que, depois que a chamada de API para fazer upload dos dados para o conjunto de dados retornar, você precisará sondar o conjunto de dados para determinar se a ingestão de dados e o processamento foram bem-sucedidos ou falharam.

Para determinar o state do conjunto de dados, use Receber 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 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 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 receber 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 receber informações completas sobre erros, chame a 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 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 vai 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 estiver vazio, não haverá 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 um máximo de 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, o estado do conjunto de dados é definido como STATE_COMPLETED. Isso significa que o conjunto de dados está pronto para uso no seu app. Para determinar o state do conjunto de dados, consulte Receber um conjunto de dados.

Você também pode fazer 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 que você fez 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 os novos dados forem enviados:

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 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 permanece como a versão "ativa" e é a versão usada pelo seu app.