Tworzenie wybranych tras

Z tego artykułu 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 z tymi informacjami:
  • 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"
}

Tworzenie tras zbiorczo

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ład kodu pokazuje strukturę odpowiedzi 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"
    }
  ]
}

Utwórz trasę z punktami pośrednimi

Aby utworzyć trasę przechodzącą przez określone punkty między punktem początkowym a docelowym, uwzględnij tablicę intermediates w obiekcie dynamicRoute w treści żądania. Każdy element w tablicy intermediates jest punktem kontrolnym zdefiniowanym przez latitude i longitude. Trasa może mieć maksymalnie 25 punktów kontrolnych.

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"

Wykorzystaj niestandardowe atrybuty trasy

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, gdzie każdy atrybut jest parą klucz-wartość. Do każdej trasy możesz podać maksymalnie 10 niestandardowych par klucz-wartość.

Atrybuty te są przydatne do identyfikowania konkretnych tras lub grupowania tras w oparciu o kryteria odpowiadające potrzebom.

Poniżej przedstawiono kilka przykładów atrybutów trasy, których można 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 prefiksu goog.
  • Długość każdego klucza i każdej wartości nie może przekraczać 100 znaków.

Następnie możesz używać tych niestandardowych routeAttributes w statystykach zarządzania drogami na te sposoby:

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

Poniższy przykład kodu pokazuje, jak utworzyć SelectedRoute z niestandardowym 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"