Janelas de tempo

As janelas de tempo especificam o momento dos eventos em um trajeto. Esses eventos podem incluir o início e o fim do trajeto de um motorista, os horários programados de retirada e entrega ou a duração de um trajeto inteiro.

As janelas de tempo podem apoiar objetivos como:

• Priorize a conclusão de retiradas e entregas dentro dos prazos especificados.
• Planeje rotas para operar dentro do horário de funcionamento geral.
• Garantir que os veículos iniciem e terminem os trajetos dentro dos prazos especificados.

Estrutura

Como mostrado no diagrama, as janelas de tempo são estruturadas da seguinte maneira:

• globalStartTime e globalEndTime são propriedades de ShipmentModel
• timeWindows são propriedades de:
  • pickups dentro de Shipment.
  • deliveries dentro de Shipment.
• startTimeWindows e endTimeWindows são propriedades de Vehicle.

Lista de verificação do Essentials

A lista de verificação a seguir descreve o conhecimento essencial que evita possíveis erros relacionados a janelas de tempo. Essa lista pode ajudar você a validar sua solicitação e resolver problemas com a resposta.

Todas as janelas de tempo de remessa e veículo precisam estar dentro da janela de tempo globalStartTime e globalEndTime.

As janelas de tempo de remessas e veículos precisam usar o tipo de mensagem TimeWindow.

Os valores de globalStartTime e globalEndTime são carimbos de data/hora, ao contrário de outras janelas de tempo que usam o tipo de mensagem TimeWindow.

É possível ter vários objetos TimeWindow para uma determinada remessa e veículo.

Um Vehicle tem dois tipos de propriedades de janela de tempo: startTimeWindows e endTimeWindows, que definem um intervalo de tempo em que um veículo deve começar e terminar as rotas, respectivamente.

Para remessas, timeWindows se aplicam apenas ao horário de início de uma retirada ou entrega. A duração de uma visita pode se estender além da janela de tempo, mas precisa se encaixar no horário de funcionamento do veículo e na janela de tempo global.

Propriedades

A tabela a seguir descreve as propriedades da janela de tempo global.

Propriedade	Formato	Descrição
globalStartTime	Timestamp	O horário mais cedo para qualquer evento.
globalEndTime	Timestamp	O horário mais recente de qualquer evento.

A tabela a seguir descreve as propriedades da janela de tempo em envios e veículos.

Com filhos	Propriedade	Formato	Descrição
Shipment.pickups	timeWindows	Matriz de tipos de mensagem TimeWindow.	Especifica intervalos de tempo para uma retirada de remessa.
Shipment.deliveries	timeWindows		Especifica intervalos de tempo para uma entrega.
Vehicle	startTimeWindows		Especifica o horário de início da programação de operação de um veículo.
	endTimeWindows		Especifica o horário de término da programação de operação de um veículo.

Observação: as programações de veículos também podem ser afetadas por BreakRules, que definem períodos em que os operadores de veículos podem fazer pausas. Para mais detalhes, consulte a documentação de referência do BreakRule.

A tabela a seguir descreve as propriedades de um tipo de mensagem TimeWindow.

Propriedade	Formato	Descrição
startTime	String (formato RFC3339 UTC "Zulu")	O início de um período.
endTime	String (formato RFC3339 UTC "Zulu")	O fim de um período.

Exemplos

Esta seção aborda três tipos de exemplos:

• Exemplos de código que ilustram a estrutura das janelas de tempo.
• Um cenário de exemplo que mostra uma maneira de usar janelas de tempo para atingir um objetivo de negócio.
• Um exemplo de solicitação que inclui os valores definidos no cenário de exemplo.

Amostras de código

As seções a seguir mostram exemplos de código de diferentes tipos de janelas de tempo.

Janelas de tempo globais

O exemplo de código a seguir mostra a estrutura das janelas de tempo globais:

{
  "model": {
    "globalStartTime": "YYYY-MM-DDTHH:MM:SSZ",
    "globalEndTime": "YYYY-MM-DDTHH:MM:SSZ",
    "shipments": [ ... ],
    "vehicles": [ ... ]
  }
}

Janelas de tempo de retiradas e entregas

O exemplo de código a seguir mostra a estrutura das janelas de tempo nas coletas e entregas de uma remessa:

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "timeWindows": [
              {
                "startTime": "YYYY-MM-DDTHH:MM:SSZ",
                "endTime": "YYYY-MM-DDTHH:MM:SSZ"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "timeWindows": [
              {
                "startTime": "YYYY-MM-DDTHH:MM:SSZ",
                "endTime": "YYYY-MM-DDTHH:MM:SSZ"
              }
            ]
          }
        ]
      }
    ],
    "vehicles": [ ... ]
  }
}

Janelas de tempo do veículo

O exemplo de código a seguir mostra a estrutura das janelas de tempo de um veículo:

{
  "model": {
    "shipments": [ ... ],
    "vehicles": [
      {
        "startTimeWindows": [
          {
            "startTime": "YYYY-MM-DDTHH:MM:SSZ",
            "endTime": "YYYY-MM-DDTHH:MM:SSZ"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "YYYY-MM-DDTHH:MM:SSZ",
            "endTime": "YYYY-MM-DDTHH:MM:SSZ"
          }
        ]
      }
    ]
  }
}

Exemplo de cenário

Nesta seção, usamos um cenário de negócios de creche para cachorros. O exemplo otimiza as rotas para buscar e deixar cachorros de duas casas diferentes, e os proprietários têm as mesmas janelas de horário para buscar e deixar os animais. O otimizador precisa respeitar o horário de funcionamento da creche, as janelas específicas de retirada e entrega para os clientes e o horário de trabalho do motorista.

Neste exemplo, os valores de propriedade na solicitação são os seguintes:

Com filhos	Propriedade	Valor	Cenário
ShipmentModel	globalStartTime	2023-01-13T07:00:00Z	Representa o horário de abertura da creche para cães. Não é possível fazer retiradas ou entregas antes desse horário.
ShipmentModel	globalEndTime	2023-01-13T19:00:00Z	Representa o horário de fechamento da creche para cães. Todas as retiradas e entregas precisam ser concluídas até esse horário.
Shipment.pickups	timeWindows	startTime: 2023-01-13T07:30:00Z	Define o período aceitável para buscar um cachorro na casa de um cliente. Neste exemplo, você informou aos dois clientes que eles deveriam estar disponíveis para retirada entre 7h30 e 9h.
		endTime: 2023-01-13T09:00:00Z
Shipment.deliveries	timeWindows	startTime: 2023-01-13T17:00:00Z	Define o período aceitável para deixar um cachorro na casa de um cliente. Neste exemplo, você informou aos dois clientes que os cachorros serão entregues entre 17h e 18h30.
		endTime: 2023-01-13T18:30:00Z
Vehicle	startTimeWindows	startTime: 2023-01-13T07:00:00Z endTime: 2023-01-13T07:15:00Z	Define a janela aceitável para o veículo iniciar (das 7h às 7h15) e terminar (das 17h às 17h15).
	endTimeWindows	startTime: 2023-01-13T18:45:00Z endTime: 2023-01-13T19:00:00Z

O diagrama a seguir ilustra as janelas de tempo que afetam essa rota.

Nesse cenário, conforme ilustrado pelo diagrama, as janelas de tempo funcionam da seguinte maneira:

• A janela de tempo global representa o horário de funcionamento da creche para cães, e todas as outras janelas de tempo precisam estar dentro dela.
• As coletas e entregas têm o próprio timeWindows no início e no fim do dia, respectivamente.
• O startTimeWindows do veículo fornece ao operador um período em que ele precisa começar a trabalhar, e o endTimeWindows fornece outro período em que ele precisa terminar o dia.
• O horário de início do primeiro startTimeWindow e o horário de término do último endTimeWindow definem o horário de funcionamento do veículo, que, neste caso, é o mesmo da janela de tempo global.

Exemplo de solicitação

O exemplo a seguir mostra a estrutura de uma solicitação optimizeTours que incorpora os valores de janelas de tempo do cenário de exemplo.

{
  "model": {
    "globalStartTime": "2023-01-13T07:00:00Z",
    "globalEndTime": "2023-01-13T19:00:00Z",
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            },
            "timeWindows": [
              {
                "startTime": "2023-01-13T07:30:00Z",
                "endTime": "2023-01-13T09:00:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            },
            "timeWindows": [
              {
                "startTime": "2023-01-13T17:00:00Z",
                "endTime": "2023-01-13T18:30:00Z"
              }
            ]
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            },
            "timeWindows": [
              {
                "startTime": "2023-01-13T07:30:00Z",
                "endTime": "2023-01-13T09:00:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            },
            "timeWindows": [
              {
                "startTime": "2023-01-13T17:00:00Z",
                "endTime": "2023-01-13T18:30:00Z"
              }
            ]
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2023-01-13T07:00:00Z",
            "endTime": "2023-01-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2023-01-13T18:45:00Z",
            "endTime": "2023-01-13T19:00:00Z"
          }
        ]
      }
    ]
  }
}

Janelas de tempo flexíveis

As janelas de tempo podem ser usadas como restrições flexíveis definindo softStartTime e softEndTime em um tipo de mensagem TimeWindow. Isso permite que o otimizador se desvie da janela de tempo especificada a um custo especificado, priorizando a otimização geral em vez da adesão estrita aos períodos, quando benéfico.

As janelas de tempo flexíveis têm as seguintes limitações de uso:

• Eles não podem ser aplicados a globalStartTime e globalEndTime porque não usam o tipo de mensagem TimeWindow.
• Eles só são aplicáveis quando há um único TimeWindow em uma lista.

Propriedades

A tabela a seguir descreve as propriedades de restrição flexível para janelas de tempo.

Nome da propriedade	Formato	Descrição da propriedade
softStartTime	Carimbo de data/hora	Especifica o início da janela de tempo flexível. Se um evento ocorrer antes desse horário, um custo será gerado.
softEndTime	Carimbo de data/hora	Especifica o fim da janela de tempo flexível. Se um evento ocorrer após esse horário, um custo será gerado.
costPerHourBeforeSoftStartTime	número	O custo por hora incorrido quando um evento começa antes de softStartTime. Essa propriedade é obrigatória ao usar softStartTime. Consulte o conceito principal Modelo de custo para saber como implementar custos.
costPerHourAfterSoftEndTime	número	O custo por hora incorrido quando um evento termina após o softEndTime. Essa propriedade é obrigatória ao usar softEndTime. Consulte o conceito principal Modelo de custo para saber como implementar custos.

Exemplo de código

O exemplo a seguir mostra a estrutura das propriedades de restrição flexível de um tipo de mensagem TimeWindow:

    {
      "softStartTime": "SOFT_START_TIME",
      "softEndTime": "SOFT_END_TIME",
      "costPerHourBeforeSoftStartTime": COST_BEFORE_START_TIME,
      "costPerHourAfterSoftEndTime": COST_AFTER_END_TIME
    }