Interpretar a resposta

A API Route Optimization retorna trajetos para veículos na solicitação correspondente. Os envios são atribuídos a veículos ou podem ser ignorados, dependendo das propriedades da solicitação.

Uma mensagem OptimizeToursResponse (REST, gRPC) tem duas propriedades principais de nível superior:

• routes[] são os trajetos para cada veículo com as remessas atribuídas. Cada Route contém métricas que refletem as propriedades desse trajeto individual.
• metrics são métricas agregadas para toda a resposta, em todos os veículos e planos de trajetos. As métricas de nível superior contêm as mesmas propriedades que as métricas por trajeto, com valores agregados em todos os trajetos.

Algumas propriedades nem sempre serão preenchidas, dependendo dos resultados da otimização:

1. skippedShipments[] lista remessas que não são realizadas por nenhum veículo. Uma remessa pode ser ignorada se não puder ser realizada dentro das restrições especificadas ou se o custo para realizar a remessa exceder o custo de penalidade. Por exemplo, se a retirada ou a entrega de uma remessa tiver um timeWindow muito estreito, talvez não seja possível ou econômico para um veículo realizar a visita durante o período necessário.
2. validationErrors[] especifica erros que tornam a solicitação inválida ou impossível de resolver quando o solvingMode da solicitação está definido como VALIDATE_ONLY. No modo DEFAULT_SOLVE normal, os erros de validação vão aparecer em uma mensagem de erro em vez de no corpo da resposta. O modo de solução VALIDATE_ONLY pode informar vários erros de uma só vez, o que é útil para depurar solicitações rapidamente.

Observação: para interpretar uma resposta, a solicitação correspondente é necessária. A resposta contém referências a entidades na solicitação, tornando a resposta difícil de interpretar por si só. Algumas mensagens, como Shipment e Vehicle, têm propriedades de rótulo para facilitar a correspondência dos dados de solicitação e resposta.

Propriedades da rota

Cada entrada routes[] é uma mensagem ShipmentRoute (REST, gRPC). Cada ShipmentRoute representa a atribuição de trajeto de um veículo específico da solicitação. Propriedades ShipmentRoute importantes relacionadas ao Vehicle correspondente incluem:

• vehicleIndex é o índice baseado em zero do Vehicle na mensagem de solicitação correspondente. As respostas REST omitem essa propriedade quando o valor é zero.
• vehicleStartTime é a hora em que o veículo precisa iniciar o trajeto.
• vehicleEndTime é a hora em que o veículo deve terminar o trajeto.

Em resposta, routes terá esta aparência:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

Observação :as respostas REST usam a representação JSON dos Buffers de protocolo, que omite campos que têm o valor padrão do respectivo tipo e que não aceitam campo presente. Isso significa que propriedades inteiras, como vehicleIndex, são omitidas quando os valores delas são zero. Consulte também a documentação oficial de mapeamento JSON de buffers de protocolo.

Cada ShipmentRoute inclui uma lista ordenada de visits que o veículo vai concluir. Cada Visit (REST, gRPC) representa um VisitRequest (REST, gRPC) da solicitação correspondente. As propriedades importantes do Visit incluem:

• shipmentIndex é o índice baseado em zero da remessa a que a visita pertence na solicitação correspondente.
• isPickup é verdadeiro quando uma visita é para retirada e falso quando ela é uma entrega. As respostas REST omitem essa propriedade quando o valor é falso.
• visitRequestIndex é o índice baseado em zero do VisitRequest de Shipment.pickups ou Shipment.deliveries na solicitação correspondente que o Visit representa. As respostas REST omitem essa propriedade quando o valor é zero.
• startTime é o horário que a visita deve começar.
• loadDemands mapeia o tipo de carregamento para carregar o valor exigido para concluir o Visit. Os valores de carga são negativos para visitas de entrega, representando a carga sendo removida do veículo.

Confira um exemplo de Visit:

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

Cada ShipmentRoute inclui uma lista ordenada de transitions que representa o deslocamento entre visits de um determinado veículo. As propriedades importantes da mensagem Transition (REST, gRPC) incluem:

• startTime é o momento em que o veículo vai começar a fazer a transição.
• travelDuration é o período que o veículo precisa percorrer para concluir a transição.
• travelDistanceMeters é a distância em metros que o veículo precisa percorrer para concluir a transição.
• trafficInfoUnavailable indica se os dados de tráfego estão disponíveis para a transição.
• waitDuration representa o tempo ocioso que o veículo passa aguardando antes de iniciar o próximo Visit. Isso pode ocorrer devido ao start_time dos Visit a seguir.
• totalDuration é a duração total da transição, incluindo os tempos de viagem, espera, intervalo e atraso.
• vehicleLoads mapeia o tipo de carregamento para a quantidade de carga carregada pelo veículo durante essa transição.

Confira um exemplo de Transition:

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

A relação entre vists e transitions é descrita em Otimização de ordem de retirada e entrega, bem como na documentação de referência ShipmentRoute (REST, gRPC).

Propriedades de métricas

A mensagem Metrics (REST, gRPC) resume toda a solução. Algumas propriedades importantes do Metrics incluem:

• totalCost é o custo total incorrido na conclusão dos trajetos. Leia mais sobre os custos em Parâmetros do modelo de custo.
• usedVehicleCount é o número total de veículos usados na solução. Os veículos podem ter trajetos vazios quando o otimizador determina que o uso deles é desnecessário.
• skippedMandatoryShipmentCount é o número de remessas ignoradas que são "obrigatórias". Uma remessa obrigatória não especifica um penaltyCost que será incorrido se for pulada. As remessas obrigatórias ainda podem ser ignoradas se o desempenho não for viável dentro das restrições especificadas. Leia mais sobre custos em Parâmetros do modelo de custo.

Métricas adicionais são informadas como mensagens AggregatedMetrics (REST, gRPC). O tipo de mensagem AggregatedMetrics é usado para a propriedade Metrics.aggregatedRouteMetrics e para a propriedade ShipmentRoute.metrics Metrics.aggregatedRouteMetrics contém métricas agregadas em todos os ShipmentRoutes na OptimizeToursResponse. Cada propriedade ShipmentRoute.metrics contém métricas para esse ShipmentRoute específico.

As propriedades AggregatedMetrics importantes incluem:

• performedShipmentCount é o número de envios realizados por veículos ao longo de todas as rotas.
• travelDuration é o tempo total que os veículos passam em trânsito enquanto completam os trajetos.
• waitDuration é o tempo total que os veículos passam esperando enquanto completam os trajetos.
• delayDuration é o tempo de atraso total dos veículos. Esse valor geralmente é zero, a menos que TransitionAttributes sejam usados na solicitação.
• breakDuration é o tempo total que os veículos passam em intervalos ao concluir os trajetos.
• visitDuration é o tempo total que os veículos passam realizando visitas enquanto concluem os trajetos. Ela é efetivamente a soma de todos os valores de VisitRequest.duration para VisitRequests correspondentes aos Visits atribuídos ao veículo aplicável.
• totalDuration é a duração total necessária para concluir os trajetos dos veículos.
• travelDistanceMeters é a distância total percorrida pelos veículos enquanto concluem os trajetos.
• maxLoads mapeia os tipos de carga para a quantidade máxima de carga carregada pelos veículos em qualquer ponto dos trajetos.

Veja abaixo um exemplo de mensagem Metrics:

{
  "routes": [
    ...
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}

Importante :se todos os custos forem zero nas mensagens Metrics ou ShipmentRoute, é improvável que o otimizador tenha encontrado uma ordem ideal para a conclusão de Visit. Pelo menos um parâmetro de custo precisa ser especificado, como Vehicle.costPerKilometer ou globalDurationCostPerHour. Caso contrário, o otimizador poderá retornar qualquer solução que satisfaça as restrições especificadas.

Exemplo completo

Um exemplo de resposta completa para a solicitação de Criar uma solicitação será semelhante a este:

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2024-02-13T00:19:31Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1151s",
          "travelDistanceMeters": 9599,
          "waitDuration": "0s",
          "totalDuration": "1151s",
          "startTime": "2024-02-13T00:19:31Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2322s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2322s",
        "travelDistanceMeters": 18603
      },
      "routeCosts": {
        "model.vehicles.cost_per_kilometer": 18.603
      },
      "routeTotalCost": 18.603
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}