REST Resource: providers.tasks

Recurso: tarefa

Uma tarefa na API Delivery representa uma única ação a ser rastreada. Em geral, há uma distinção entre as tarefas relacionadas ao envio e as tarefas de pausa. Um envio pode ter várias tarefas associadas. Por exemplo, pode haver uma tarefa para a coleta e outra para a entrega ou transferência. Além disso, diferentes tarefas de um determinado envio podem ser tratadas por veículos diferentes. Por exemplo, um veículo pode fazer a coleta, levando o envio para o centro de distribuição, enquanto outro leva o mesmo envio do centro de distribuição ao local de entrega.

Observação: as APIs gRPC e REST usam convenções de nomenclatura de campo diferentes. Por exemplo, o campo Task.journey_sharing_info na API gRPC e o campo Task.journeySharingInfo na API REST se referem ao mesmo campo.

Representação JSON 
{
  "name": string,
  "type": enum (Type),
  "state": enum (State),
  "taskOutcome": enum (TaskOutcome),
  "taskOutcomeTime": string,
  "taskOutcomeLocation": {
    object (LocationInfo)
  },
  "taskOutcomeLocationSource": enum (TaskOutcomeLocationSource),
  "trackingId": string,
  "deliveryVehicleId": string,
  "plannedLocation": {
    object (LocationInfo)
  },
  "taskDuration": string,
  "targetTimeWindow": {
    object (TimeWindow)
  },
  "journeySharingInfo": {
    object (JourneySharingInfo)
  },
  "taskTrackingViewConfig": {
    object (TaskTrackingViewConfig)
  },
  "attributes": [
    {
      object (TaskAttribute)
    }
  ]
}
Campos
name

string

Precisa estar no formato providers/{provider}/tasks/{task}.
type

enum (Type)

Obrigatório. Imutável. Define o tipo da tarefa. Por exemplo, uma pausa ou um envio.
state

enum (State)

Obrigatório. O estado de execução atual da tarefa.
taskOutcome

enum (TaskOutcome)

O resultado da tarefa.
taskOutcomeTime

string (Timestamp format)

O carimbo de data/hora que indica quando o resultado do Task foi definido pelo provedor.

Usa o RFC 3339, em que a saída gerada é sempre normalizada em Z e usa dígitos fracionários 0, 3, 6 ou 9. Deslocamentos diferentes de "Z" também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
taskOutcomeLocation

object (LocationInfo)

O local em que o resultado de Task foi definido. Esse valor é atualizado como parte de tasks.patch. Se esse valor não for atualizado explicitamente pelo provedor, o Fleet Engine vai preenchê-lo por padrão com o último local conhecido do veículo (o local bruto).
taskOutcomeLocationSource

enum (TaskOutcomeLocationSource)

Indica de onde veio o valor do taskOutcomeLocation.
trackingId

string

Imutável. Esse campo facilita o armazenamento de um ID para que você evite usar um mapeamento complicado. Não é possível definir trackingId para tarefas do tipo UNAVAILABLE e SCHEDULED_STOP. Esses IDs estão sujeitos às seguintes restrições:

  • Precisa ser uma string Unicode válida.
  • Limitado a um comprimento máximo de 64 caracteres.
  • Normalizado de acordo com o Formulário de normalização C do Unicode.
  • Não pode conter nenhum dos seguintes caracteres ASCII: '/', ':', '?', ',' ou '#'.
deliveryVehicleId

string

Apenas saída. O ID do veículo que está executando essa tarefa. Os IDs dos veículos de entrega estão sujeitos às seguintes restrições:

  • Precisa ser uma string Unicode válida.
  • Limitado a um comprimento máximo de 64 caracteres.
  • Normalizado de acordo com o Formulário de normalização C do Unicode.
  • Não pode conter nenhum dos seguintes caracteres ASCII: '/', ':', '?', ',' ou '#'.
plannedLocation

object (LocationInfo)

Imutável. O local em que a tarefa será concluída. Opcional para tarefas UNAVAILABLE, mas obrigatório para todas as outras tarefas.
taskDuration

string (Duration format)

Obrigatório. Imutável. O tempo necessário para executar uma tarefa nesse local.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
targetTimeWindow

object (TimeWindow)

Janela de tempo em que a tarefa precisa ser concluída.
journeySharingInfo

object (JourneySharingInfo)

Apenas saída. Campos específicos para compartilhamento de jornadas. Não é preenchido quando o estado é CLOSED.
taskTrackingViewConfig

object (TaskTrackingViewConfig)

A configuração para o acompanhamento de tarefas que especifica quais elementos de dados são visíveis para os usuários finais e em quais circunstâncias.
attributes[]

object (TaskAttribute)

Uma lista de atributos de tarefas personalizados. Cada atributo precisa ter uma chave exclusiva.

Tipo

O tipo de tarefa.

Enums
TYPE_UNSPECIFIED Por padrão, o tipo de tarefa é desconhecido.
PICKUP Uma tarefa de retirada é a ação realizada para retirar uma remessa de um cliente. As retiradas de veículos de depósito ou de veículos de alimentação precisam usar o tipo SCHEDULED_STOP.
DELIVERY Uma tarefa de entrega é a ação realizada para entregar um envio a um cliente final. As entregas de veículos de depósito ou de veículos de alimentação precisam usar o tipo SCHEDULED_STOP.
SCHEDULED_STOP Uma tarefa de parada programada é usada para fins de planejamento. Por exemplo, ele pode representar a coleta ou entrega de remessas de veículos de apoio ou depósitos. Ele não deve ser usado para envios que são retirados ou entregues de um cliente final.
UNAVAILABLE Uma tarefa que significa que o veículo não está disponível para manutenção. Por exemplo, isso pode acontecer quando o motorista faz uma pausa ou quando o veículo está sendo abastecido.

TaskOutcomeLocationSource

A identidade da origem que preencheu o taskOutcomeLocation.

Enums
TASK_OUTCOME_LOCATION_SOURCE_UNSPECIFIED O resultado da tarefa antes de ser definido.
PROVIDER O provedor especificou o taskOutcomeLocation.
LAST_VEHICLE_LOCATION O provedor não especificou o taskOutcomeLocation. Portanto, o Fleet Engine usou a última localização conhecida do veículo.

JourneySharingInfo

Campos específicos de compartilhamento da jornada.

Representação JSON 
{
  "remainingVehicleJourneySegments": [
    {
      object (VehicleJourneySegment)
    }
  ],
  "lastLocation": {
    object (DeliveryVehicleLocation)
  },
  "lastLocationSnappable": boolean
}
Campos
remainingVehicleJourneySegments[]

object (VehicleJourneySegment)

Informações de rastreamento das paradas que o veículo atribuído vai fazer antes de concluir a tarefa. Essa lista pode conter paradas de outras tarefas.

O primeiro segmento, Task.journey_sharing_info.remaining_vehicle_journey_segments[0] (gRPC) ou Task.journeySharingInfo.remainingVehicleJourneySegments[0] (REST), contém informações de rota do último local conhecido do motorista até o próximo VehicleStop. As informações da rota atual geralmente vêm do app do motorista, exceto em alguns casos indicados na documentação de DeliveryVehicle.current_route_segment. Os outros segmentos em Task.journey_sharing_info.remaining_vehicle_journey_segments (gRPC) ou Task.journeySharingInfo.remainingVehicleJourneySegments (REST) são preenchidos pelo Fleet Engine. Eles fornecem informações de rota entre os VehicleStops restantes.
lastLocation

object (DeliveryVehicleLocation)

Indica o último local informado do veículo atribuído.
lastLocationSnappable

boolean

Indica se o lastLocation do veículo pode ser fixado no currentRouteSegment. Esse valor é falso se lastLocation ou currentRouteSegment não existir. Esse valor é calculado pelo Fleet Engine. As atualizações dos clientes são ignoradas.

TaskTrackingViewConfig

A mensagem de configuração que define quando um elemento de dados de uma tarefa deve ficar visível para os usuários finais.

Representação JSON 
{
  "routePolylinePointsVisibility": {
    object (VisibilityOption)
  },
  "estimatedArrivalTimeVisibility": {
    object (VisibilityOption)
  },
  "estimatedTaskCompletionTimeVisibility": {
    object (VisibilityOption)
  },
  "remainingDrivingDistanceVisibility": {
    object (VisibilityOption)
  },
  "remainingStopCountVisibility": {
    object (VisibilityOption)
  },
  "vehicleLocationVisibility": {
    object (VisibilityOption)
  }
}
Campos
routePolylinePointsVisibility

object (VisibilityOption)

Campo que especifica quando os pontos de poligonal da rota podem ficar visíveis. Se esse campo não for especificado, a configuração de visibilidade padrão no nível do projeto para esses dados será usada.
estimatedArrivalTimeVisibility

object (VisibilityOption)

Campo que especifica quando o horário de chegada estimado pode ser mostrado. Se esse campo não for especificado, a configuração de visibilidade padrão no nível do projeto para esses dados será usada.
estimatedTaskCompletionTimeVisibility

object (VisibilityOption)

Campo que especifica quando o tempo estimado para a conclusão da tarefa pode ficar visível. Se esse campo não for especificado, a configuração de visibilidade padrão no nível do projeto para esses dados será usada.
remainingDrivingDistanceVisibility

object (VisibilityOption)

Campo que especifica quando a distância restante da viagem pode ser mostrada. Se esse campo não for especificado, a configuração de visibilidade padrão no nível do projeto para esses dados será usada.
remainingStopCountVisibility

object (VisibilityOption)

Campo que especifica quando a contagem de paradas restantes pode ser visível. Se esse campo não for especificado, a configuração de visibilidade padrão no nível do projeto para esses dados será usada.
vehicleLocationVisibility

object (VisibilityOption)

Campo que especifica quando a localização do veículo pode ficar visível. Se esse campo não for especificado, a configuração de visibilidade padrão no nível do projeto para esses dados será usada.

VisibilityOption

A mensagem de opção que define quando um elemento de dados deve ficar visível para os usuários finais.

Representação JSON 
{

  // Union field visibility_option can be only one of the following:
  "remainingStopCountThreshold": integer,
  "durationUntilEstimatedArrivalTimeThreshold": string,
  "remainingDrivingDistanceMetersThreshold": integer,
  "always": boolean,
  "never": boolean
  // End of list of possible types for union field visibility_option.
}
Campos
Campo de união visibility_option. A opção de visibilidade específica escolhida. visibility_option pode ser apenas de um dos tipos a seguir:
remainingStopCountThreshold

integer

Esse elemento de dados fica visível para os usuários finais se a contagem de paradas restante for <= remainingStopCountThreshold.
durationUntilEstimatedArrivalTimeThreshold

string (Duration format)

Esse elemento de dados fica visível para os usuários finais se o ETA até a parada for <= durationUntilEstimatedArrivalTimeThreshold.

Duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".
remainingDrivingDistanceMetersThreshold

integer

Esse elemento de dados fica visível para os usuários finais se a distância restante em metros <= remainingDrivingDistanceMetersThreshold.
always

boolean

Se definido como "true", esse elemento de dados fica sempre visível para os usuários finais sem limites. Não é possível definir esse campo como falso.
never

boolean

Se definido como "true", esse elemento de dados fica sempre oculto dos usuários finais sem limites. Não é possível definir esse campo como falso.

Métodos

batchCreate

 Cria e retorna um lote de novos objetos Task.

create

 Cria e retorna um novo objeto Task.

get

 Recebe informações sobre um Task.

list

 Recebe todos os Tasks que atendem aos critérios de filtragem especificados.

patch

 Atualiza os dados de Task.