Tworzenie wybranych tras

W sekcjach poniżej dowiesz się, jak tworzyć trasy i dodawać atrybuty niestandardowe za pomocą interfejsu Roads Selection API:

Utworzenie trasy

Aby utworzyć trasę, wyślij żądanie POST do punktu końcowego create.

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID

Treść żądania musi być obiektem JSON, który definiuje zasób SelectedRoute. Ten obiekt zawiera te informacje:

  • Obiekt dynamicRoute zawierający te informacje:
  • unikalny selectedRouteId, Ta wartość musi mieć od 4 do 63 znaków i zawierać tylko znaki alfanumeryczne. Jeśli nie podasz identyfikatora, system wygeneruje unikalny identyfikator dla wybranej trasy.

Poniższy przykładowy kod pokazuje strukturę żądania POST do punktu końcowego create.

curl -X POST -d '
    {"dynamic_route": { \
      origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, \
      destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE} \
    }}' \' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

Jeśli operacja się uda, interfejs API zwróci zasób SelectedRoute. Odpowiedź zawiera selectedRouteId w polu name. Możesz użyć tego obiektu selectedRouteId, aby pobrać lub usunąć zasób SelectedRoute.

Poniższy przykładowy kod pokazuje strukturę odpowiedzi punktu końcowego create, która wskazuje powodzenie operacji.

{
  "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID",
  "dynamicRoute": {
    "origin": {
      "latitude": ORIGIN_LATITUDE,
      "longitude": ORIGIN_LONGITUDE
    },
    "destination": {
      "latitude": DESTINATION_LATITUDE,
      "longitude": DESTINATION_LONGITUDE
    }
  },
  "createTime": "CREATE_TIME",
  "state": "STATE_VALIDATING"
}

Zbiorcze tworzenie tras

Aby utworzyć wiele tras w jednym żądaniu, użyj punktu końcowego batchCreate. Ten punkt końcowy umożliwia zdefiniowanie maksymalnie 1000 tras w jednym wywołaniu.

Wyślij żądanie POST do punktu końcowego batchCreate:

https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate

Adres URL używa składni transkodowania gRPC.

Treść żądania musi być obiektem JSON zawierającym tablicę requests. Każdy obiekt w tej tablicy to CreateSelectedRouteRequest, który definiuje pojedynczy zasób SelectedRoute.

Poniższy przykładowy kod pokazuje strukturę żądania POST do punktu końcowego batchCreate:

curl -X POST -d '
    {"requests": [
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_1, "longitude": ORIGIN_LONGITUDE_1},
          "destination": {"latitude": DESTINATION_LATITUDE_1, "longitude": DESTINATION_LONGITUDE_1}
        },
        "selectedRouteId": "route-one"
      },
      {
        "dynamicRoute": {
          "origin": {"latitude": ORIGIN_LATITUDE_2, "longitude": ORIGIN_LONGITUDE_2},
          "destination": {"latitude": DESTINATION_LATITUDE_2, "longitude": DESTINATION_LONGITUDE_2}
        },
        "selectedRouteId": "route-two"
      }
    ]}
  ' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes:batchCreate"

Jeśli operacja się uda, interfejs API zwróci odpowiedź zawierającą tablicę utworzonych zasobów SelectedRoute.

Poniższy przykładowy kod pokazuje strukturę odpowiedzi z punktu końcowego batchCreate:

{
  "selectedRoutes": [
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_1",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_1,
          "longitude": ORIGIN_LONGITUDE_1
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_1,
          "longitude": DESTINATION_LONGITUDE_1
        }
      },
      "createTime": "CREATE_TIME_1",
      "state": "STATE_VALIDATING"
    },
    {
      "name": "projects/PROJECT_NUMBER/selectedRoutes/SELECTED_ROUTE_ID_2",
      "dynamicRoute": {
        "origin": {
          "latitude": ORIGIN_LATITUDE_2,
          "longitude": ORIGIN_LONGITUDE_2
        },
        "destination": {
          "latitude": DESTINATION_LATITUDE_2,
          "longitude": DESTINATION_LONGITUDE_2
        }
      },
      "intermediates": [],
      "createTime": "CREATE_TIME_2",
      "state": "STATE_VALIDATING"
    }
  ]
}

Tworzenie trasy z punktami pośrednimi

Aby utworzyć trasę, która przebiega przez określone punkty między miejscem początkowym a docelowym, w treści żądania w obiekcie dynamicRoute umieść tablicę intermediates. Każdy element w tablicy intermediates to punkt pośredni określony przez parametry latitude i longitude. Trasa może mieć maksymalnie 25 punktów pośrednich.

Poniższy przykładowy kod pokazuje, jak utworzyć SelectedRoute z pośrednimi punktami na trasie:

curl -X POST -d '
    {"dynamic_route": { \
        "origin": {"latitude": ORIGIN_LATITUDE , "longitude": ORIGIN_LONGITUDE}, \
        "intermediates": [
          {"latitude": INTERMEDIATE_LATITUDE_1, "longitude": INTERMEDIATE_LONGITUDE_1},
          {"latitude": INTERMEDIATE_LATITUDE_2, "longitude": INTERMEDIATE_LONGITUDE_2},
          {"latitude": INTERMEDIATE_LATITUDE_3, "longitude": INTERMEDIATE_LONGITUDE_3}
        ],
        "destination": {"latitude": DESTINATION_LATITUDE, "longitude": DESTINATION_LONGITUDE}}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"

Korzystanie z atrybutów trasy niestandardowej

Aby ułatwić zarządzanie trasami i analizowanie danych w usłudze Roads Management Insights, obiekt SelectedRoute zawiera pole route_attributes.

Użyj pola routeAttributes, aby zdefiniować własne właściwości niestandardowe dla poszczególnych tras. Każdy atrybut jest parą klucz-wartość. Do każdej trasy możesz podać maksymalnie 10 niestandardowych par klucz-wartość.

Te atrybuty są przydatne do identyfikowania konkretnych tras lub grupowania tras na podstawie kryteriów istotnych dla Twoich potrzeb.

Oto kilka przykładów atrybutów trasy, których możesz użyć:

  • "road_classification": "highway"
  • "maintenance_zone": "north_district"
  • "event_id": "marathon_2024"
  • "pavement_type": "asphalt"

Podczas definiowania pola routeAttributes postępuj zgodnie z tymi wskazówkami:

  • Klucze nie mogą zaczynać się od przedrostka goog.
  • Długość każdego klucza i każdej wartości nie może przekraczać 100 znaków.

Możesz używać tych niestandardowych routeAttributes w statystykach zarządzania drogami na te sposoby:

  • Filtrowanie powiadomień Pub/Sub: możesz ustawić filtry w subskrypcjach Pub/Sub, aby otrzymywać aktualizacje tylko w przypadku tras, które pasują do określonych kluczy atrybutów i ich wartości lub nie pasują do nich.
  • Udoskonalanie analizy BigQuery: w tabelach BigQuery możesz używać tych atrybutów do filtrowania konkretnych tras na podstawie wartości atrybutu. Możesz też pogrupować trasy według określonego klucza atrybutu, aby uzyskać bardziej ukierunkowaną analizę danych.

Poniższy przykładowy kod pokazuje, jak utworzyć obiekt SelectedRoute z niestandardowym obiektem routeAttributes.

curl -X POST -d '
    {"dynamic_route": { origin: {latitude: ORIGIN_LATITUDE ,longitude: ORIGIN_LONGITUDE}, destination: {latitude: DESTINATION_LATITUDE, longitude: DESTINATION_LONGITUDE}}, route_attributes: {"ATTRIBUTE_KEY":"ATTRIBUTE_VALUE"}}' \
  -H 'X-Goog-User-Project: PROJECT_NUMBER' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://roads.googleapis.com/selection/v1/projects/PROJECT_NUMBER/selectedRoutes?selectedRouteId=SELECTED_ROUTE_ID"