ShipmentRoute

A rota de um veículo pode ser decomposta, ao longo do eixo do tempo, desta forma (assumimos que há n visitas):

  |            |            |          |       |  T[2], |        |      |
  | Transition |  Visit #0  |          |       |  V[2], |        |      |
  |     #0     |    aka     |   T[1]   |  V[1] |  ...   | V[n-1] | T[n] |
  |  aka T[0]  |    V[0]    |          |       | V[n-2],|        |      |
  |            |            |          |       | T[n-1] |        |      |
  ^            ^            ^          ^       ^        ^        ^      ^
vehicle    V[0].start   V[0].end     V[1].   V[1].    V[n].    V[n]. vehicle
 start     (arrival)   (departure)   start   end      start    end     end

Observe que há uma diferença entre:

  • "Eventos pontuais", como o início e o fim do veículo e o início e o fim de cada visita (ou seja, a chegada e a partida). Eles acontecem em um determinado segundo.
  • "intervalos de tempo", como as visitas em si e a transição entre elas. Embora os intervalos de tempo às vezes tenham duração zero, ou seja, começam e terminam no mesmo segundo, eles geralmente têm uma duração positiva.

Invariantes:

  • Se houver n visitas, haverá n+1 transições.
  • Uma visita é sempre cercada por uma transição anterior (mesmo índice) e uma transição posterior (índice + 1).
  • A partida do veículo é sempre seguida pela transição #0.
  • O fim do veículo é sempre precedido pela transição #n.

Veja o que acontece durante uma Transition e uma Visit:

---+-------------------------------------+-----------------------------+-->
   |           TRANSITION[i]             |           VISIT[i]          |
   |                                     |                             |
   |  * TRAVEL: the vehicle moves from   |      PERFORM the visit:     |
   |    VISIT[i-1].departure_location to |                             |
   |    VISIT[i].arrival_location, which |  * Spend some time:         |
   |    takes a given travel duration    |    the "visit duration".    |
   |    and distance                     |                             |
   |                                     |  * Load or unload           |
   |  * BREAKS: the driver may have      |    some quantities from the |
   |    breaks (e.g. lunch break).       |    vehicle: the "demand".   |
   |                                     |                             |
   |  * WAIT: the driver/vehicle does    |                             |
   |    nothing. This can happen for     |                             |
   |    many reasons, for example when   |                             |
   |    the vehicle reaches the next     |                             |
   |    event's destination before the   |                             |
   |    start of its time window         |                             |
   |                                     |                             |
   |  * DELAY: *right before* the next   |                             |
   |    arrival. E.g. the vehicle and/or |                             |
   |    driver spends time unloading.    |                             |
   |                                     |                             |
---+-------------------------------------+-----------------------------+-->
   ^                                     ^                             ^
V[i-1].end                           V[i].start                    V[i].end

Por fim, confira como TRAVEL, BREAKS, DELAY e WAIT podem ser organizados durante uma transição.

  • Elas não se sobrepõem.
  • O DELAY é único e precisa ser um período contíguo de tempo antes da próxima visita (ou término do veículo). Portanto, basta saber a duração do atraso para saber o início e o fim.
  • Os intervalos são períodos de tempo contíguos e não sobrepostos. A resposta especifica o horário de início e a duração de cada intervalo.
  • TRAVEL e WAIT são "preemptáveis": eles podem ser interrompidos várias vezes durante essa transição. Os clientes podem presumir que a viagem vai acontecer "assim que possível" e que o tempo restante será preenchido com "espera".

Um exemplo (complexo):

                               TRANSITION[i]
--++-----+-----------------------------------------------------------++-->
  ||     |       |           |       |           |         |         ||
  ||  T  |   B   |     T     |       |     B     |         |    D    ||
  ||  r  |   r   |     r     |   W   |     r     |    W    |    e    ||
  ||  a  |   e   |     a     |   a   |     e     |    a    |    l    ||
  ||  v  |   a   |     v     |   i   |     a     |    i    |    a    ||
  ||  e  |   k   |     e     |   t   |     k     |    t    |    y    ||
  ||  l  |       |     l     |       |           |         |         ||
  ||     |       |           |       |           |         |         ||
--++-----------------------------------------------------------------++-->
Representação JSON 
{
  "vehicleIndex": integer,
  "vehicleLabel": string,
  "vehicleStartTime": string,
  "vehicleEndTime": string,
  "visits": [
    {
      object (Visit)
    }
  ],
  "transitions": [
    {
      object (Transition)
    }
  ],
  "hasTrafficInfeasibilities": boolean,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "breaks": [
    {
      object (Break)
    }
  ],
  "metrics": {
    object (AggregatedMetrics)
  },
  "routeCosts": {
    string: number,
    ...
  },
  "routeTotalCost": number
}
Campos
vehicleIndex

integer

Veículo que executa a rota, identificado pelo índice na origem ShipmentModel.
vehicleLabel

string

Rótulo do veículo que executa essa rota, igual a ShipmentModel.vehicles(vehicleIndex).label, se especificado.
vehicleStartTime

string (Timestamp format)

Hora em que o veículo inicia o trajeto.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
vehicleEndTime

string (Timestamp format)

Hora em que o veículo termina o trajeto.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
visits[]

object (Visit)

Sequência ordenada de visitas que representa uma rota. visits[i] é a i-ésima visita na rota. Se esse campo estiver vazio, o veículo será considerado como não utilizado.
transitions[]

object (Transition)

Lista ordenada de transições para a rota.
hasTrafficInfeasibilities

boolean

Quando OptimizeToursRequest.consider_road_traffic é definido como verdadeiro, esse campo indica que as inconsistências nos horários da rota são previstas usando estimativas de duração da viagem com base no trânsito. Pode não haver tempo suficiente para concluir as viagens ajustadas ao tráfego, os atrasos e os intervalos entre as visitas, antes da primeira visita ou depois da última visita, e ainda atender aos períodos de visita e do veículo. Por exemplo,

  startTime(previous_visit) + duration(previous_visit) +
  travelDuration(previous_visit, next_visit) > startTime(next_visit)

A chegada em next_visit provavelmente vai acontecer mais tarde do que a janela de tempo atual devido ao aumento da estimativa de tempo de viagem travelDuration(previous_visit, next_visit) devido ao trânsito. Além disso, um intervalo pode ser forçado a se sobrepor a uma visita devido a um aumento nas estimativas de tempo de deslocamento e restrições de intervalo de tempo de visita ou intervalo.
routePolyline

object (EncodedPolyline)

A representação codificada da polilinha do trajeto. Esse campo só será preenchido se OptimizeToursRequest.populate_polylines estiver definido como verdadeiro.
breaks[]

object (Break)

Pausas programadas para o veículo que faz essa rota. A sequência breaks representa intervalos de tempo, cada um começando no startTime correspondente e durando duration segundos.
metrics

object (AggregatedMetrics)

Métricas de duração, distância e carga para essa rota. Os campos de AggregatedMetrics são somados em todos os ShipmentRoute.transitions ou ShipmentRoute.visits, dependendo do contexto.
routeCosts

map (key: string, value: number)

Custo da rota, detalhado por campos de solicitação relacionados a custos. As chaves são caminhos proto, em relação à entrada OptimizeToursRequests, por exemplo, "model.shipments.pickups.cost", e os valores são o custo total gerado pelo campo de custo correspondente, agregado em todo o trajeto. Em outras palavras, costs["model.shipments.pickups.cost"] é a soma de todos os custos de retirada no trajeto. Todos os custos definidos no modelo são informados em detalhes aqui, exceto os custos relacionados a TransitionAttributes, que são informados de forma agregada a partir de 01/2022.
routeTotalCost

number

Custo total da rota. A soma de todos os custos no mapa de custos.

Acesse

Uma visita realizada durante uma rota. Essa visita corresponde à retirada ou entrega de um Shipment.

Representação JSON 
{
  "shipmentIndex": integer,
  "isPickup": boolean,
  "visitRequestIndex": integer,
  "startTime": string,
  "loadDemands": {
    string: {
      object (Load)
    },
    ...
  },
  "detour": string,
  "shipmentLabel": string,
  "visitLabel": string
}
Campos
shipmentIndex

integer

Índice do campo shipments na ShipmentModel de origem.
isPickup

boolean

Se verdadeiro, a visita corresponde à retirada de um Shipment. Caso contrário, ele corresponde a uma entrega.
visitRequestIndex

integer

Índice de VisitRequest no campo de retirada ou entrega do Shipment (consulte isPickup).
startTime

string (Timestamp format)

Horário em que a visita começa. O veículo pode chegar antes disso ao local da visita. Os horários são consistentes com o ShipmentModel.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
loadDemands

map (key: string, value: object (Load))

Demanda total de carga de visitas como a soma do envio e da solicitação de visita loadDemands. Os valores são negativos se a visita for uma entrega. As demandas são informadas para os mesmos tipos do Transition.loads (consulte este campo).
detour

string (Duration format)

Tempo de desvio extra devido aos envios visitados no trajeto antes da visita e ao possível tempo de espera induzido pelas janelas de tempo. Se a visita for uma entrega, o desvio será calculado a partir da visita de retirada correspondente e será igual a:

startTime(delivery) - startTime(pickup)
- (duration(pickup) + travel duration from the pickup location
to the delivery location).

Caso contrário, ele é calculado com base no startLocation do veículo e é igual a:

startTime - vehicleStartTime - travel duration from
the vehicle's `startLocation` to the visit.

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

string

Cópia do Shipment.label correspondente, se especificado no Shipment.
visitLabel

string

Cópia do VisitRequest.label correspondente, se especificado no VisitRequest.

Transição

Transição entre dois eventos na rota. Consulte a descrição de ShipmentRoute.

Se o veículo não tiver startLocation e/ou endLocation, as métricas de viagem correspondentes serão 0.

Representação JSON 
{
  "travelDuration": string,
  "travelDistanceMeters": number,
  "trafficInfoUnavailable": boolean,
  "delayDuration": string,
  "breakDuration": string,
  "waitDuration": string,
  "totalDuration": string,
  "startTime": string,
  "routePolyline": {
    object (EncodedPolyline)
  },
  "routeToken": string,
  "vehicleLoads": {
    string: {
      object (VehicleLoad)
    },
    ...
  }
}
Campos
travelDuration

string (Duration format)

Duração da viagem durante essa transição.

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

number

Distância percorrida durante a transição.
trafficInfoUnavailable

boolean

Quando o tráfego é solicitado por OptimizeToursRequest.consider_road_traffic e as informações de tráfego não podem ser recuperadas para um Transition, esse booleano é definido como verdadeiro. Isso pode ser temporário (problema raro nos servidores de trânsito em tempo real) ou permanente (nenhum dado para esse local).
delayDuration

string (Duration format)

Soma das durações de atraso aplicadas a essa transição. Se houver, o atraso começa exatamente delayDuration segundos antes do próximo evento (visita ou fim do veículo). Consulte os TransitionAttributes.delay.

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

string (Duration format)

Soma da duração das pausas ocorridas durante essa transição, se houver. Os detalhes sobre a hora de início e a duração de cada intervalo são armazenados em ShipmentRoute.breaks.

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

string (Duration format)

Tempo gasto esperando durante essa transição. A duração da espera corresponde ao tempo de inatividade e não inclui o tempo de intervalo. Além disso, esse tempo de espera pode ser dividido em vários intervalos não contíguos.

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

string (Duration format)

Duração total da transição, fornecida para conveniência. É igual a:

  • próxima visita startTime (ou vehicleEndTime se for a última transição) startTime da transição;
  • Se ShipmentRoute.has_traffic_infeasibilities for falso, o seguinte também será verdadeiro: "totalDuration = travelDuration + delayDuration
  • breakDuration + waitDuration`.

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

string (Timestamp format)

Horário de início desta transição.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
routePolyline

object (EncodedPolyline)

A representação codificada da polilinha do trajeto seguido durante a transição. Esse campo só será preenchido se populateTransitionPolylines estiver definido como verdadeiro.
routeToken

string

Apenas saída. Um token opaco que pode ser transmitido ao SDK Navigation para reconstruir a rota durante a navegação e, em caso de redirecionamento, respeitar a intenção original quando a rota foi criada. Tratar esse token como um blob opaco. Não compare o valor entre as solicitações, porque ele pode mudar mesmo que o serviço retorne a mesma rota. Esse campo só será preenchido se populateTransitionPolylines estiver definido como verdadeiro.
vehicleLoads

map (key: string, value: object (VehicleLoad))

Cargas de veículos durante essa transição, para cada tipo que aparece na Vehicle.load_limits do veículo ou que tem Shipment.load_demands diferente de zero em algum envio realizado nessa rota.

As cargas durante a primeira transição são as cargas iniciais da rota do veículo. Depois, após cada visita, o loadDemands da visita é adicionado ou subtraído para receber as cargas da próxima transição, dependendo se a visita foi uma retirada ou uma entrega.

EncodedPolyline

A representação codificada de uma polilinha. Saiba mais sobre a codificação de polilinhas aqui: https://developers.google.com/maps/documentation/utilities/polylinealgorithm https://developers.google.com/maps/documentation/javascript/reference/geometry#encoding.

Representação JSON 
{
  "points": string
}
Campos
points

string

String que representa os pontos codificados da polilinha.

Intervalo

Dados que representam a execução de uma pausa.

Representação JSON 
{
  "startTime": string,
  "duration": string
}
Campos
startTime

string (Timestamp format)

Horário de início de um intervalo.

Um carimbo de data/hora no formato RFC3339 UTC "Zulu", com resolução de nanossegundos e até nove dígitos fracionários. Exemplos: "2014-10-02T15:01:23Z" e "2014-10-02T15:01:23.045123456Z".
duration

string (Duration format)

Duração de uma pausa.

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