Interpretar a resposta

A API Route Optimization retorna trajetos para veículos no solicitação. As remessas são atribuídas a veículos ou podem ser ignoradas dependendo da propriedades da solicitação.

Uma mensagem OptimizeToursResponse (REST e gRPC) tem duas mensagens principais propriedades:

• routes[] são as rotas de cada veículo com os envios atribuídos. Cada Route contém métricas que refletem as propriedades desse trajeto individual.
• metrics são métricas agregadas da resposta inteira, em todas veículos e planos de trajetos. As métricas de nível superior contêm as mesmas propriedades por rota, com valores agregados em todas as rotas.

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. Um envio pode ser pulado se não puder ser realizado dentro das restrições especificadas ou se o custo para realizar o envio exceder o custo da multa. Por exemplo, se a coleta ou entrega de um envio tiver uma timeWindow muito estreita, 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 do corpo da resposta. O modo de resolução VALIDATE_ONLY pode informar vários erros de uma só vez, o que é útil para depurar rapidamente as solicitações.

.

Observação: para interpretar uma resposta, é necessária a solicitação correspondente. A resposta contém referências a entidades na solicitação, dificultando a resposta da resposta a interpretar por conta própria. Algumas mensagens como Shipment e Vehicle têm marcadores propriedades para facilitar a correspondência de 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 para um veículo específico de da solicitação. Propriedades ShipmentRoute importantes relacionadas à Vehicle incluem:

• vehicleIndex é o índice baseado em zero do Vehicle no com a mensagem de solicitação. 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 os campos que têm o valor padrão do tipo correspondente e que não oferecem suporte ao campo presente. Isso significa que propriedades inteiras, como vehicleIndex, são são omitidos quando seus valores são zero. Consulte também a documentação oficial do JSON de buffers de protocolo Documentação de mapeamento (em inglês).

Cada ShipmentRoute inclui uma lista ordenada de visits que o veículo vai concluir. Cada Visit (REST, gRPC) representa um objeto 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 é entrega. As respostas REST omitem essa propriedade quando o valor é falso.
• visitRequestIndex é o índice baseado em zero do VisitRequest nas Shipment.pickups ou Shipment.deliveries na solicitação correspondente que Visit representa. As respostas REST omitem essa propriedade quando o valor é zero.
• startTime é o horário de início previsto da visita.
• loadDemands tipo de carregamento de mapas para o valor de carregamento exigido para concluir o Visit. Os valores de carga são negativos para as visitas de entrega, representando a carga removida do veículo.

Um exemplo de Visit tem esta aparência:

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

Cada ShipmentRoute inclui uma lista ordenada de transitions que representa viagem entre visits em 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 é a duração que o veículo precisa percorrer até concluir a transição.
• travelDistanceMeters é a distância em metros que o veículo precisa para concluir a transição.
• trafficInfoUnavailable indica se os dados de tráfego estão disponíveis para o a transição.
• waitDuration representa o tempo ocioso que o veículo gasta esperando antes de poder iniciar o próximo Visit. Isso pode ocorrer devido ao start_time do após Visit.
• totalDuration é a duração total da transição, incluindo viagens, tempo de espera, intervalo e atraso.
• vehicleLoads mapeia o tipo de carregamento para a quantidade 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 do pedido de retirada e entrega, assim 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. Ler mais sobre os custos nos 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ária.
• skippedMandatoryShipmentCount é o número de remessas ignoradas que são "obrigatório". Um envio obrigatório não especifica um penaltyCost que seja caso o envio seja pulado. Os envios obrigatórios ainda podem ser ignorado se o desempenho não for viável de acordo com as restrições especificadas. Saiba mais sobre os custos em Parâmetros do modelo de custo.

Outras métricas são informadas como mensagens AggregatedMetrics (REST, gRPC). O tipo de mensagem AggregatedMetrics é usado nas propriedade Metrics.aggregatedRouteMetrics e para a ShipmentRoute.metrics a propriedade Metrics.aggregatedRouteMetrics contém métricas agregadas de todas ShipmentRoutes na OptimizeToursResponse. Cada ShipmentRoute.metrics contém métricas para aquela ShipmentRoute específica.

As propriedades AggregatedMetrics importantes incluem:

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

Um exemplo de mensagem Metrics tem esta aparência:

{
  "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, ou o otimizador pode retornar qualquer solução que satisfaça as restrições especificadas.

Exemplo completo

Um exemplo de resposta completo para a solicitação de Construct a Request é parecido com como:

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