Como selecionar uma entidade usando alertas

Os alertas podem ser vinculados a diferentes entidades de um feed e aplicados simultaneamente a uma combinação de paradas, estações, agências, trajetos e muito mais.

Neste artigo, você conhecerá algumas combinações comuns em que os alertas podem ser aplicados.

Uso de informed_entity

Quando mais de um valor informed_entity é especificado para um único alerta, esse alerta é aplicado às entidades que atendem a qualquer um dos valores especificados.

No exemplo abaixo, há dois valores informed_entity, cada um especificando um trajeto diferente. Dessa forma, o alerta é aplicado a todas as viagens dos dois trajetos e todas as paradas usadas em viagens dos dois trajetos.

id: "2"
alert {
  informed_entity {
    route_id: "1"
  }
  informed_entity {
    route_id: "2"
  }
  ...
}

Quando vários campos são preenchidos para o mesmo valor informed_entity, ele é aplicado somente nas entidades que atendem a todos os valores preenchidos.

No exemplo abaixo, o informed_entity especifica um route_id e um stop_id. Isso se aplica apenas aos alertas de viagens do trajeto nesta parada específica. Ele não será exibido se uma viagem do trajeto não usar a parada especificada durante o percurso e vice-versa (ou seja, se uma viagem usar a parada especificada que não pertencer ao trajeto).

id: "2"
alert {
  informed_entity {
    route_id: "1"
    stop_id: "2"
  }
  ...
}

Uso de active_period

O campo trip de informed_entity permite selecionar a data e a hora específicas da viagem. Os outros campos permitem selecionar entidades como paradas afetadas, mas não fornecem informações suficientes para indicar quando os alertas devem ser aplicados.

O valor active_period precisa ser usado em combinação com informed_entity para definir o período em que o alerta será aplicado às respectivas entidades. No entanto, isso não define quando o alerta será visto pelos usuários.

Por exemplo, imagine que um alerta seja criado no dia 20 de dezembro com um active_period que afeta todas as viagens em 25 de dezembro.

Os usuários poderão visualizar o alerta se pesquisarem, a partir de 20 de dezembro, viagens que estarão em operação no dia 25 de dezembro. No entanto, eles não poderão pesquisar viagens que estiverem fora do active_period definido.

Se o valor active_period não for fornecido, o alerta será aplicado na informed_entity imediatamente após a criação e será aplicado até que seja removido do feed.

Para evitar o conhecimento prévio do conteúdo do alerta, crie o alerta somente quando quiser que os usuários os vejam. Por exemplo, os alertas sobre as novas medidas de distanciamento social só devem ser publicados após a comunicação oficial pela imprensa.

Combinações de seletores de entidade

Extensão da área atendida pela agência

Aplicado às seguintes entidades:

• Todos os trajetos e viagens da agência
• Todas as paradas usadas nas viagens da agência

Detalhes da implementação

• O valor informed_entity precisa ter apenas o campo agency_id preenchido.
• O valor active_period precisa definir o período em que esse alerta ficará em vigor.

Exemplo de cenário: informativo sobre uma falha no trilho que afeta todos os trens da agência A das 10h às 12h no dia 20 de dezembro.

id: "1"
alert {
  informed_entity {
    agency_id: "A"
  }
  active_period {
    start: 1608458400
    end: 1608465600
  }
  effect: MODIFIED_SERVICE
  cause: OTHER_CAUSE
  ...
}

Trajeto

Aplicado às seguintes entidades:

• Todas as viagens do trajeto especificado
• Todas as paradas das viagens do trajeto

Detalhes da implementação

• O valor informed_entity precisa ter somente o campo route_id preenchido.
• O valor active_period precisa definir o período em que o alerta ficará em vigor.

Exemplo de cenário: o trajeto turístico foi cancelado entre os dias 10 e 20 de dezembro devido a uma emergência médica.

id: "1"
alert {
  informed_entity {
    route_id: "12"
  }
  active_period {
    start: 1607558400
    end: 1608508799
  }
  effect: NO_SERVICE
  cause: MEDICAL_EMERGENCY
  ...
}

Trajeto em um sentido específico

Aplicado às seguintes entidades:

• Todas as viagens do trajeto especificado que têm o direction_id especificado.
• Todos as paradas das viagens do trajeto

Detalhes da implementação

• O valor informed_entity precisa ter os campos route_id e direction_id preenchidos.
• O valor active_period precisa definir o período em que o alerta ficará em vigor.

Exemplo de cenário: o trajeto turístico foi cancelado entre os dias 10 e 20 de dezembro devido a uma emergência médica.

id: "1"
alert {
  informed_entity {
    route_id: "12"
    direction_id: 1
  }
  active_period {
    start: 1607558400
    end: 1608508799
  }
  effect: NO_SERVICE
  cause: MEDICAL_EMERGENCY
  ...
}

Meio de transporte

Aplicado às seguintes entidades:

• Todas as viagens com o tipo de trajeto especificado
• Todas as paradas das viagens do trajeto

Detalhes da implementação

• O valor informed_entity precisa ter somente o campo route_id preenchido.
• O valor active_period precisa definir o período em que o alerta ficará em vigor.

Exemplo de cenário: todas as viagens de balsa foram canceladas no dia 20 de dezembro devido a uma enchente.

id: "1"
alert {
  informed_entity {
    route_type: 4
  }
  active_period {
    start: 1608422400
    end: 1608508799
  }
  effect: NO_SERVICE
  cause: WEATHER
  ...
}

Parada

Aplicado às seguintes entidades:

• Todas as viagens que usam esta parada
• A própria parada

Detalhes da implementação

• O valor informed_entity precisa ter somente o campo stop_id preenchido.
• O valor active_period precisa definir o período em que o alerta ficará em vigor.

Exemplo de cenário: a parada ficará fechada de 10 a 20 de dezembro devido a obras.

id: "1"
alert {
  informed_entity {
    stop_id: "4"
  }
  active_period {
    start: 1607558400
    end: 1608508799
  }
  effect: NO_SERVICE
  cause: CONSTRUCTION
  ...
}

Viagem

Aplicado às seguintes entidades:

• Todas as viagens que usam esta parada
• Todas as paradas da viagem

Detalhes da implementação

• Para mais informações, consulte o artigo Como selecionar uma viagem.