Interpretar a resposta

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

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

• 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.
• metrics são métricas agregadas para toda a resposta, em todos os veículos e planos de rota. As métricas de nível superior contêm as mesmas propriedades que as métricas por rota, com valores agregados em todas as rotas.

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

1. skippedShipments[] lista os envios que não são realizados 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ário fazer a solicitação correspondente. A resposta contém referências a entidades na solicitação, o que dificulta a interpretação dela por conta própria. 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 rota para um veículo específico da solicitação. As propriedades importantes do ShipmentRoute 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 é o horário em que o veículo precisa iniciar o trajeto.
• vehicleEndTime é o tempo em que o veículo deve terminar a rota.

Em uma resposta, routes vai ser parecido com:

{
  "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 tipo respectivo e que não oferecem suporte ao campo presente. Isso significa que propriedades inteiras como vehicleIndex são omitidas quando os valores 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 com base em zero da remessa a que essa visita pertence na solicitação correspondente.
• isPickup é verdadeiro quando uma visita é uma retirada e falso quando é uma entrega. As respostas REST omitem essa propriedade quando o valor é falso.
• visitRequestIndex é o índice baseado em zero da VisitRequest de Shipment.pickups ou Shipment.deliveries na solicitação correspondente que a Visit representa. As respostas REST omitem essa propriedade quando o valor é zero.
• startTime é o horário de início previsto da visita.
• loadDemands mapeia o tipo de carga para a quantidade de carga exigida 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 representam viagens entre visits para 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 em que o veículo precisa viajar 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 de inatividade que o veículo passa esperando antes de poder iniciar a próxima Visit. Isso pode ocorrer devido ao start_time do Visit a seguir.
• totalDuration é a duração total da transição, incluindo o tempo de deslocamento, de espera, de pausa e de atraso.
• vehicleLoads mapeia o tipo de carga para a quantidade de carga transportada pelo veículo durante essa transição.

Um exemplo de Transition tem esta aparência:

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

Para mais informações sobre a relação entre vists e transitions, consulte Otimização da ordem de retirada e entrega e a documentação de referência ShipmentRoute (REST, gRPC). Para mais informações sobre as propriedades routePolyline e routeToken de uma mensagem Transition, consulte Polilinhas de transição e tokens de rota.

Propriedades de métricas

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

• totalCost é o custo total incorrido na conclusão das rotas. 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 rotas vazias quando o otimizador determina que o uso deles é desnecessário.
• skippedMandatoryShipmentCount é o número de envios pulados que são "obrigatórios". Um envio obrigatório não especifica um penaltyCost que seja incorrido se o envio for ignorado. Os envios obrigatórios ainda podem ser ignorados se a execução não for viável com as restrições especificadas. Leia 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 para a propriedade Metrics.aggregatedRouteMetrics e para a propriedade ShipmentRoute.metrics. Metrics.aggregatedRouteMetrics contém métricas agregadas em todos os ShipmentRoutes no OptimizeToursResponse. Cada propriedade ShipmentRoute.metrics contém métricas para esse ShipmentRoute específico.

As propriedades importantes do AggregatedMetrics 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 concluem as rotas.
• delayDuration é o tempo total de atraso dos veículos. Ele geralmente é zero, a menos que TransitionAttributes seja usado na solicitação.
• breakDuration é o tempo total que os veículos passam em pausas enquanto concluem as rotas.
• visitDuration é o tempo total que os veículos passam realizando visitas enquanto concluem as 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 carga para a quantidade máxima de carga transportada pelos veículos em qualquer ponto das rotas.

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. Caso contrário, o otimizador poderá retornar qualquer solução que atenda às restrições especificadas.

Exemplo completo

Um exemplo completo de resposta para a solicitação de Criar uma solicitação é 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
    }
  }
}