เริ่มต้นใช้งาน Fleet Engine

API การเดินทางและการนำส่งแบบออนดีมานด์ของ Fleet Engine ช่วยให้คุณจัดการการเดินทางและสถานะของยานพาหนะสำหรับแอปพลิเคชันการเดินทางและความคืบหน้าของคำสั่งซื้อได้ โดยจะจัดการธุรกรรมระหว่าง Driver SDK, Consumer SDK และบริการแบ็กเอนด์ของคุณ ซึ่งสื่อสารกับ Fleet Engine ได้โดยการเรียกใช้ gRPC หรือ REST

สิ่งที่ต้องดำเนินการก่อน

สำหรับการพัฒนา ให้ตรวจสอบว่าคุณติดตั้ง Cloud SDK (gcloud) และได้รับการตรวจสอบสิทธิ์สำหรับโปรเจ็กต์แล้ว

Shell

gcloud auth login

คุณควรเห็นข้อความดำเนินการสำเร็จ เช่น

You are now logged in as [my-user@example.com].
Your current project is [project-id].  You ...

ตรวจสอบว่าได้กำหนดค่า API ของโซลูชัน Fleet Engine สำหรับเรียกรถและการนำส่งแบบออนดีมานด์อย่างเหมาะสม

Shell

gcloud --project=project-id services enable fleetengine.googleapis.com

หากคำสั่งนี้ทำให้เกิดข้อผิดพลาด โปรดตรวจสอบกับผู้ดูแลระบบโปรเจ็กต์และตัวแทนทีมสนับสนุนของ Google เพื่อขอสิทธิ์เข้าถึง

Logging

Fleet Engine จะเขียนข้อความบันทึกเกี่ยวกับการเรียก API ที่ได้รับลงใน บันทึกของ Google Cloud Platform ได้ ดูภาพรวมเกี่ยวกับวิธีอ่านและวิเคราะห์บันทึกในเอกสาร Cloud Logging

โปรเจ็กต์ที่สร้างก่อนวันที่ 10 ก.พ. 2022 อาจไม่ได้เปิดใช้การบันทึกโดยค่าเริ่มต้น ดูรายละเอียดเพิ่มเติมได้ในเอกสารการบันทึก

ไลบรารีไคลเอ็นต์

เราเผยแพร่ไลบรารีของไคลเอ็นต์ในภาษาโปรแกรมทั่วไปหลายภาษา ไลบรารีเหล่านี้จะช่วยให้นักพัฒนาแอปได้รับประสบการณ์การใช้งานที่ดีขึ้นผ่าน REST หรือ gRPC แบบข้อมูลดิบ โปรดดูวิธีการรับไลบรารีของไคลเอ็นต์สำหรับแอปพลิเคชันเซิร์ฟเวอร์ที่หัวข้อไลบรารีของไคลเอ็นต์

ตัวอย่าง Java ในเอกสารประกอบนี้จะถือว่าคุ้นเคยกับ gRPC อยู่แล้ว

การตรวจสอบสิทธิ์และการให้สิทธิ์

คุณสามารถกำหนดค่าความสามารถที่ให้บริการโดย "การเดินทางและความคืบหน้าในการสั่งซื้อ" ผ่าน Google Cloud Console API และ SDK เหล่านี้ต้องใช้ JSON Web Token ที่ลงนามแล้วโดยใช้บัญชีบริการที่สร้างขึ้นจาก Cloud Console

ตั้งค่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์

หากต้องการตั้งค่าโปรเจ็กต์ระบบคลาวด์ ให้สร้างโปรเจ็กต์ก่อนแล้วจึงสร้างบัญชีบริการ

วิธีสร้างโปรเจ็กต์ Google Cloud

  1. สร้างโปรเจ็กต์ Google Cloud โดยใช้ Google Cloud Console
  2. เปิดใช้ API และแดชบอร์ดบริการเพื่อเปิดใช้ Local Rides and Deliveries API

บัญชีบริการเชื่อมโยงกับบทบาทอย่างน้อย 1 บทบาท โดยใช้เพื่อสร้างเว็บโทเค็น JSON ที่ให้สิทธิ์ชุดต่างๆ โดยขึ้นอยู่กับบทบาท โดยปกติแล้ว เพื่อลดความเสี่ยงจากการละเมิด คุณสามารถสร้างบัญชีบริการหลายบัญชีโดยให้แต่ละบัญชีมีชุดบทบาทขั้นต่ำที่จำเป็น

ความคืบหน้าการเดินทางและคําสั่งซื้อใช้บทบาทต่อไปนี้

บทบาทคำอธิบาย
ผู้ใช้ Fleet Engine Consumer SDK

roles/fleetengine.consumerSdkUser		 ให้สิทธิ์ในการค้นหายานพาหนะและเรียกข้อมูลเกี่ยวกับยานพาหนะและการเดินทาง โดยทั่วไปแล้ว โทเค็นที่สร้างโดยบัญชีบริการที่มีบทบาทนี้จะนำไปใช้จากอุปกรณ์เคลื่อนที่ของแอปบริการร่วมเดินทางหรือบริการจัดส่งสำหรับผู้ใช้ทั่วไป
ผู้ใช้ Fleet Engine Driver SDK

roles/fleetengine.driverSdkUser		 ให้สิทธิ์อัปเดตตำแหน่งและเส้นทางของยานพาหนะ รวมถึงเรียกข้อมูลเกี่ยวกับยานพาหนะและการเดินทาง โดยทั่วไปแล้ว โทเค็นที่สร้างโดยบัญชีบริการที่มีบทบาทนี้จะมาจากอุปกรณ์เคลื่อนที่ แอปบริการร่วมเดินทางหรือคนขับรถส่งของ
ผู้ดูแลระบบตามคำขอของ Fleet Engine

roles/fleetengine.ondemandAdmin		 มอบสิทธิ์การอ่านและเขียนทรัพยากรยานพาหนะและการเดินทางทั้งหมด ผู้ใช้หลักที่มีบทบาทนี้ไม่จำเป็นต้องใช้ JWT และควรใช้ข้อมูลเข้าสู่ระบบเริ่มต้นของแอปพลิเคชันแทน ระบบจะไม่พิจารณาการอ้างสิทธิ์ JWT ที่กำหนดเอง บทบาทนี้ควรจำกัดเฉพาะสภาพแวดล้อมที่เชื่อถือได้ (แบ็กเอนด์ของลูกค้า)
ผู้ใช้บริการ FleetEngine ระดับสูง **(เลิกใช้งานแล้ว)**

roles/fleetengine.serviceSuperUser		 ให้สิทธิ์แก่ API ของยานพาหนะและการเดินทางทั้งหมด โดยทั่วไปจะใช้โทเค็นที่สร้างโดยบัญชีบริการที่มีบทบาทนี้จากเซิร์ฟเวอร์แบ็กเอนด์ของคุณ บทบาทนี้เลิกใช้งานแล้ว โปรดใช้ roles/fleetengine.ondemandAdmin แทน

ตัวอย่างเช่น สร้างบัญชีบริการให้กับแต่ละบทบาททั้ง 3 บทบาท และมอบหมายบทบาทที่เกี่ยวข้อง

gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.consumerSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.driverSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-su
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.serviceSuperUser

Driver และ Consumer SDK สร้างขึ้นตามบทบาทมาตรฐานเหล่านี้

อีกทางเลือกหนึ่งคือ คุณอาจสร้างบทบาทที่กำหนดเอง ซึ่งอนุญาตให้รวมชุดสิทธิ์ที่กำหนดเองเข้าด้วยกัน SDK ไดรเวอร์และผู้บริโภคจะแสดงข้อความแสดงข้อผิดพลาดเมื่อใดก็ตามที่ไม่มีสิทธิ์ที่จำเป็น ด้วยเหตุนี้ เราขอแนะนำอย่างยิ่งให้ใช้ชุดบทบาทมาตรฐานที่แสดงด้านบนและไม่ใช้บทบาทที่กำหนดเอง

หากจำเป็นต้องสร้างโทเค็น JWT สำหรับไคลเอ็นต์ที่ไม่น่าเชื่อถือ การเพิ่มผู้ใช้ลงในบทบาทผู้สร้างโทเค็นบัญชีบริการจะช่วยให้ผู้ใช้สร้างโทเค็นด้วยเครื่องมือบรรทัดคำสั่ง gcloud ได้

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

โดยที่ my-user@example.com คืออีเมลที่ใช้ในการตรวจสอบสิทธิ์กับ gcloud (gcloud auth list --format='value(account)')

ไลบรารีการตรวจสอบสิทธิ์ Fleet Engine

Fleet Engine ใช้ JSON Web Token (JWT) เพื่อจำกัดการเข้าถึง API ของ Fleet Engine ไลบรารีการตรวจสอบสิทธิ์ Fleet Engine ใหม่มีให้ใช้ใน GitHub ช่วยลดความยุ่งยากในการก่อสร้าง Fleet Engine JWT และเซ็นชื่ออย่างปลอดภัย

ไลบรารีมีประโยชน์ดังต่อไปนี้

  • ลดความซับซ้อนของกระบวนการสร้างโทเค็น Fleet Engine
  • มีกลไกการรับรองโทเค็นที่นอกเหนือจากการใช้ไฟล์ข้อมูลเข้าสู่ระบบ (เช่น การแอบอ้างบัญชีบริการ)
  • แนบโทเค็นที่ลงชื่อไว้กับคำขอขาออกที่ส่งจากสตับ gRPC หรือไคลเอ็นต์ GAPIC

การสร้าง JSON Web Token (JWT) สำหรับการให้สิทธิ์

เมื่อไม่ได้ใช้ไลบรารีการตรวจสอบสิทธิ์ Fleet Engine คุณจะต้องสร้าง JSON Web Token (JWT) ภายในฐานของโค้ดโดยตรง คุณจึงต้องมีความเข้าใจอย่างลึกซึ้ง เกี่ยวกับ JWT และความเกี่ยวข้องกับ Fleet Engine นี่จึงเป็นเหตุผลที่เราขอแนะนำอย่างยิ่งให้ใช้ประโยชน์จากไลบรารีการตรวจสอบสิทธิ์ Fleet Engine

ใน Fleet Engine นั้น JSON Web Token (JWT) จะมีการตรวจสอบสิทธิ์ระยะเวลาสั้นๆ และช่วยให้มั่นใจว่าอุปกรณ์จะสามารถปรับเปลี่ยนยานพาหนะ การเดินทาง หรืองานที่ได้รับอนุญาตเท่านั้น JWT มีส่วนหัวและส่วนการอ้างสิทธิ์ ส่วนหัวประกอบด้วยข้อมูล เช่น คีย์ส่วนตัวที่จะใช้ (ซึ่งได้มาจากบัญชีบริการ) และอัลกอริทึมการเข้ารหัส ส่วนการอ้างสิทธิ์จะมีข้อมูลต่างๆ เช่น เวลาที่สร้างโทเค็น, Time to Live ของโทเค็น, บริการที่อ้างสิทธิ์การเข้าถึง และข้อมูลการให้สิทธิ์อื่นๆ เพื่อกำหนดขอบเขตการเข้าถึง ตัวอย่างเช่น รหัสยานพาหนะ

ส่วนหัว JWT ประกอบด้วยฟิลด์ต่อไปนี้

ฟิลด์คำอธิบาย
alg อัลกอริทึมที่จะใช้ "RS256"
typ ประเภทของโทเค็น "JWT"
บุตรหลาน รหัสคีย์ส่วนตัวของบัญชีบริการ คุณดูค่านี้ได้ในช่อง "private_key_id" ของไฟล์ JSON ของบัญชีบริการ ตรวจสอบว่าได้ใช้คีย์จากบัญชีบริการที่มีระดับสิทธิ์ที่ถูกต้อง

ส่วนการอ้างสิทธิ์ JWT ประกอบด้วยฟิลด์ต่อไปนี้

ฟิลด์คำอธิบาย
คือ อีเมลของบัญชีบริการ
สำรอง อีเมลของบัญชีบริการ
Aud SERVICE_NAME ของบัญชีบริการ ซึ่งในกรณีนี้คือ https://fleetengine.googleapis.com/
Iiat การประทับเวลาเมื่อมีการสร้างโทเค็น ซึ่งระบุเป็นวินาทีที่ผ่านไปตั้งแต่เวลา 00:00:00 น. UTC ของวันที่ 1 มกราคม 1970 โปรดรอ 10 นาทีสำหรับการเอียง หากการประทับเวลาอยู่ในอดีตหรืออนาคตมากเกินไป เซิร์ฟเวอร์อาจรายงานข้อผิดพลาด
exp การประทับเวลาเมื่อโทเค็นหมดอายุ โดยระบุเป็นวินาทีที่ผ่านไปตั้งแต่ 00:00:00 น. UTC ของวันที่ 1 มกราคม 1970 คำขอจะล้มเหลวหากการประทับเวลานานกว่า 1 ชั่วโมงในอนาคต
การให้สิทธิ์ อาจมี "vehicleid" หรือ "tripid" ขึ้นอยู่กับกรณีการใช้งาน

การสร้างโทเค็น JWT หมายถึงการลงชื่อโทเค็น ดูวิธีการและตัวอย่างโค้ดสำหรับการสร้างและการลงนาม JWT ได้ที่การให้สิทธิ์บัญชีบริการโดยไม่ใช้ OAuth จากนั้นคุณจะแนบโทเค็นที่ลงนามกับการเรียกใช้ gRPC หรือวิธีอื่นๆ ที่ใช้ในการเข้าถึง Fleet Engine ได้

การเรียกร้องสิทธิ์จาก JWT

เมื่อสร้างเพย์โหลด JWT ให้เพิ่มการอ้างสิทธิ์เพิ่มเติมในส่วนการให้สิทธิ์โดยกำหนดคีย์ vehicleid หรือ tripid เป็นค่าของรหัสยานพาหนะหรือรหัสการเดินทางที่จะเรียกใช้

Driver SDK จะใช้การอ้างสิทธิ์ vehicleid เสมอ ไม่ว่าจะดำเนินการในขณะเดินทางหรือบนยานพาหนะ แบ็กเอนด์ของ Fleet Engine รับประกันว่าพาหนะเชื่อมโยงกับการเดินทางที่ขอก่อนทำการดัดแปลง

SDK ของผู้บริโภคจะใช้การอ้างสิทธิ์ tripid เสมอ

ผู้ให้บริการเรียกรถหรือผู้ให้บริการควรใช้ vehicleid หรือ tripid พร้อม "*" เพื่อจับคู่ยานพาหนะและการเดินทางทั้งหมด โปรดทราบว่า JWT สามารถมีโทเค็นทั้งสองได้ แม้ว่าจะไม่จำเป็นก็ตาม ซึ่งอาจทำให้การติดตั้งใช้งานโทเค็นโทเค็นง่ายขึ้น

กรณีการใช้งานของ JWT

ต่อไปนี้เป็นตัวอย่างโทเค็นสำหรับเซิร์ฟเวอร์ผู้ให้บริการ

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
  "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

ข้อมูลต่อไปนี้จะแสดงโทเค็นตัวอย่างสําหรับแอปผู้บริโภค

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

ข้อมูลต่อไปนี้จะแสดงโทเค็นตัวอย่างสำหรับแอปไดรเวอร์

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}
  • สำหรับช่อง kid ในส่วนหัว ให้ระบุรหัสคีย์ส่วนตัวของบัญชีบริการ คุณดูค่านี้ได้ในช่อง private_key_id ของไฟล์ JSON ของบัญชีบริการ
  • สำหรับช่อง iss และ sub ให้ระบุอีเมลของบัญชีบริการ คุณดูค่านี้ได้ในช่อง client_email ของไฟล์ JSON ของบัญชีบริการ
  • สำหรับช่อง aud ให้ระบุ https://SERVICE_NAME/
  • สำหรับช่อง iat ให้ใช้การประทับเวลาเมื่อสร้างโทเค็น ซึ่งระบุเป็นวินาทีที่ผ่านไปตั้งแต่เวลา 00:00:00 น. ตามเขตเวลา UTC ของวันที่ 1 มกราคม 1970 โปรดรอ 10 นาทีสำหรับการเอียง หากการประทับเวลาอยู่นานเกินไปในอดีตหรือในอนาคต เซิร์ฟเวอร์อาจรายงานข้อผิดพลาด
  • สำหรับช่อง exp ให้ใช้การประทับเวลาเมื่อโทเค็นหมดอายุ ซึ่งระบุเป็นวินาทีตั้งแต่ 00:00:00 น. ตามเขตเวลา UTC ของวันที่ 1 มกราคม 1970 ค่าสูงสุดที่อนุญาตคือ iat + 3600

เมื่อลงนาม JWT เพื่อส่งไปยังอุปกรณ์เคลื่อนที่ โปรดตรวจสอบว่าได้ใช้บัญชีบริการสำหรับบทบาท Driver หรือ Consumer SDK มิเช่นนั้น อุปกรณ์เคลื่อนที่จะเปลี่ยนสถานะที่ไม่ควรจะมีได้

และในทำนองเดียวกัน เมื่อลงนามใน JWT ที่จะใช้สำหรับการโทรที่มีสิทธิ์ ให้ใช้บัญชีบริการที่มีบทบาทผู้ใช้ระดับสูง มิฉะนั้นการดำเนินการจะไม่สำเร็จ

การสร้าง JWT สำหรับการทดสอบ

การสร้างโทเค็นจากเทอร์มินัลอาจมีประโยชน์เมื่อทำการทดสอบ

บัญชีผู้ใช้ของคุณต้องมีบทบาทผู้สร้างโทเค็นบัญชีบริการจึงจะทำตามขั้นตอนเหล่านี้ได้

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

สร้างไฟล์ใหม่ชื่อ unsigned_token.json ที่มีเนื้อหาด้านล่าง พร็อพเพอร์ตี้ iat คือเวลาปัจจุบันโดยมีหน่วยเป็นวินาทีหลังจาก Epoch ซึ่งดึงข้อมูลได้โดยการเรียกใช้ date +%s ในเทอร์มินัล พร็อพเพอร์ตี้ exp คือเวลาหมดอายุในหน่วยวินาทีหลังจากเหตุการณ์ Epoch ซึ่งคํานวณได้โดยการเพิ่ม 3600 ลงใน iat เวลาหมดอายุต้องไม่เกิน 1 ชั่วโมงในอนาคต

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "sub": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

จากนั้นเรียกใช้คำสั่ง gcloud ต่อไปนี้เพื่อลงนามโทเค็นในนามของบัญชีบริการผู้ใช้ขั้นสูง

gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt

ตอนนี้ระบบควรจัดเก็บ JWT ที่เข้ารหัส Base64 ที่มีการรับรองไว้ในไฟล์ signed_token.jwt แล้ว โทเค็นจะใช้ได้เป็นเวลา 1 ชั่วโมง

ตอนนี้คุณทดสอบโทเค็นได้โดยการเรียกใช้คำสั่ง curl กับปลายทาง REST ของรายการยานพาหนะ:

curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"

ยานพาหนะและวงจร

ยานพาหนะคือเอนทิตีที่แสดงถึงคู่คนขับกับพาหนะ ปัจจุบันระบบไม่สามารถติดตามคนขับและยานพาหนะแยกกันได้ Rideshare หรือผู้ให้บริการนำส่งจะสร้างยานพาหนะโดยใช้รหัสผู้ให้บริการ (ซึ่งต้องเหมือนกับรหัสโปรเจ็กต์ของโปรเจ็กต์ Google Cloud ที่มีบัญชีบริการที่ใช้เรียก Fleet Engine API) และรหัสยานพาหนะที่ผู้บริการนำส่งรถหรือผู้ให้บริการนำส่งเป็นเจ้าของ

ระบบจะลบยานพาหนะที่ไม่ได้อัปเดตผ่าน UpdateVehicle หลังจากผ่านไป 7 วันโดยอัตโนมัติ มีข้อผิดพลาดเกิดขึ้นในการเรียก CreateVehicle ด้วยคู่รหัสผู้ให้บริการ/รหัสยานพาหนะที่มีอยู่แล้ว กรณีของยานพาหนะที่ไม่ได้อัปเดตบ่อยคุณสามารถจัดการได้ 2 วิธี ได้แก่ การเรียกใช้ CreateVehicle ด้วยการจับคู่รหัสผู้ให้บริการกับรหัสยานพาหนะที่คาดไว้ และทิ้งข้อผิดพลาดหากมียานพาหนะอยู่แล้ว หรือการเรียกใช้ CreateVehicle หลังจาก UpdateVehicle ส่งคืนพร้อมข้อผิดพลาด NOT_FOUND

การอัปเดตตำแหน่งของรถ

เพื่อประสิทธิภาพที่ดีที่สุดเมื่อใช้ Fleet Engine ให้สตรีมการอัปเดตตำแหน่งของรถ ใช้วิธีใดวิธีหนึ่งต่อไปนี้เพื่อแจ้งการอัปเดต

  1. ใช้ Driver SDK - Android, iOS -- ตัวเลือกที่ง่ายที่สุด
  2. ใช้โค้ดที่กำหนดเอง ซึ่งมีประโยชน์หากมีการส่งต่อตำแหน่งผ่านแบ็กเอนด์ของคุณ หรือหากคุณใช้อุปกรณ์อื่นที่ไม่ใช่ Android หรือ iOS

ประเภทยานพาหนะ

เอนทิตียานพาหนะมีช่องที่ต้องกรอก VehicleType ซึ่งมี enum ของ Category ซึ่งระบุได้เป็น AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE หรือ PEDESTRIAN ประเภทยานพาหนะเป็นเกณฑ์ตัวกรองใน SearchVehicles และ ListVehicles ได้

การกำหนดเส้นทางทั้งหมดสำหรับยานพาหนะจะใช้ RouteTravelMode ที่เกี่ยวข้องหากตั้งค่าหมวดหมู่เป็น AUTO, TWO_WHEELER, BICYCLE หรือ PEDESTRIAN หากตั้งค่าหมวดหมู่เป็น TAXI หรือ TRUCK ระบบจะถือว่าการกำหนดเส้นทางเหมือนกับโหมด AUTO

แอตทริบิวต์ของยานพาหนะ

เอนทิตียานพาหนะมีช่องที่ซ้ำของ VehicleAttribute Fleet Engine ไม่ได้ตีความแอตทริบิวต์เหล่านี้ SearchVehicles API มีฟิลด์ที่กำหนดให้ Vehicles ที่ตรงกันต้องมีแอตทริบิวต์ที่รวมอยู่ทั้งหมดซึ่งตั้งเป็นค่าที่ระบุ

โปรดทราบว่าช่องแอตทริบิวต์เป็นส่วนเพิ่มเติมจากช่องอื่นๆ ที่รองรับในข้อความ Vehicle เช่น vehicle_type และ supported_trip_types

จุดอ้างอิงที่เหลืออยู่ของยานพาหนะ

เอนทิตียานพาหนะมีช่องที่ซ้ำของ TripWaypoint (RPC | REST) ซึ่งเรียกว่า waypoints(RPC | REST) ฟิลด์นี้จะรวมจุดอ้างอิงที่เหลือในเส้นทาง ตามลำดับที่พาหนะไปถึงจุดเหล่านั้น Fleet Engine จะคำนวณช่องนี้เมื่อมีการกำหนดการเดินทางให้กับรถ และอัปเดตการเดินทางดังกล่าวเมื่อการเดินทางเปลี่ยนสถานะ จุดอ้างอิงเหล่านี้สามารถระบุได้จากฟิลด์ TripId และฟิลด์ WaypointType

การขยายเกณฑ์การมีสิทธิ์ของยานพาหนะสำหรับการจับคู่

โดยปกติแล้ว บริการของบริการเรียกรถหรือผู้ให้บริการจัดส่งจะรับผิดชอบในการจับคู่คำขอเดินทางไปยังยานพาหนะ บริการนี้สามารถใช้แอตทริบิวต์ยานพาหนะ เพื่อรวมยานพาหนะในการค้นหาจำนวนมาก ตัวอย่างเช่น ผู้ให้บริการสามารถใช้ชุดแอตทริบิวต์ที่สอดคล้องกับระดับของสิทธิพิเศษหรือความสามารถที่ยานพาหนะมีให้ ตัวอย่างเช่น ระดับ 3 อาจเป็นชุดแอตทริบิวต์ที่มีค่าบูลีน ได้แก่ is_bronze_level, is_silver_level และ is_gold_level ยานพาหนะ มีสิทธิ์แสดงบนทั้ง 3 ประเภท เมื่อ Fleet Engine ได้รับคำขอสำหรับการเดินทางที่ต้องใช้ความสามารถระดับเงิน การค้นหาจะรวมยานพาหนะดังกล่าวไว้ด้วย การใช้แอตทริบิวต์ลักษณะนี้รวมถึงยานพาหนะที่มีความสามารถที่หลากหลาย

อัปเดตแอตทริบิวต์ยานพาหนะได้ 2 วิธี วิธีแรกคือ API UpdateVehicle เมื่อใช้ API นี้ แอตทริบิวต์ของยานพาหนะทั้งชุดจะได้รับการตั้งค่าเป็นค่า เป็นไปไม่ได้ที่จะอัปเดตเพียงแอตทริบิวต์เดียว อีกวิธีหนึ่งคือ API ของ UpdateVehicleAttributes วิธีนี้จะทำให้ระบบอัปเดตเฉพาะแอตทริบิวต์เท่านั้น ระบบจะกำหนดแอตทริบิวต์ที่รวมอยู่ในคำขอเป็นค่าใหม่ หรือมีการเพิ่มแอตทริบิวต์ที่ไม่ระบุ จะไม่มีการเปลี่ยนแปลง

วิธีการ: สร้างยานพาหนะ

คุณต้องสร้างเอนทิตี Vehicle สำหรับยานพาหนะแต่ละคันที่จะติดตามภายในกลุ่ม

ใช้ปลายทาง CreateVehicle กับ CreateVehicleRequest เพื่อสร้างยานพาหนะ

provider_id ของ Vehicle ต้องเป็นรหัสโปรเจ็กต์ (เช่น my-on-demand-project) ของโปรเจ็กต์ Google Cloud ที่มีบัญชีบริการที่จะใช้เรียก Fleet Engine โปรดทราบว่าแม้บัญชีบริการหลายบัญชีอาจเข้าถึง Fleet Engine สำหรับ Rideshare หรือผู้ให้บริการนำส่งรายเดียว แต่ขณะนี้ Fleet Engine ยังไม่รองรับบัญชีบริการจากโปรเจ็กต์ Google Cloud หลายโปรเจ็กต์ที่เข้าถึง Vehicles เดียวกัน

คุณสร้าง Vehicle ได้ในสถานะ OFFLINE หรือ ONLINE หากสร้าง ONLINE ระบบอาจแสดงผล URL นั้นทันทีตามคำค้นหา SearchVehicles

ระบบอาจรวม last_location เริ่มต้นในการโทร CreateVehicle แม้ว่าได้รับอนุญาต คุณไม่ควรสร้าง Vehicle ในสถานะ ONLINE โดยไม่มี last_location

ดูรายละเอียดเกี่ยวกับช่องประเภทยานพาหนะได้ที่ประเภทยานพาหนะ

ดูรายละเอียดเกี่ยวกับ ช่องแอตทริบิวต์ได้ที่แอตทริบิวต์ยานพาหนะ

ค่าที่แสดงผลจาก CreateVehicle คือเอนทิตี Vehicle ที่สร้างขึ้น

ตัวอย่าง

Shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "OFFLINE",
    "supportedTripTypes": ["EXCLUSIVE"],
    "maximumCapacity": 4,
    "vehicleType": {"category": "AUTO"},
    "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

ดูข้อมูลอ้างอิง providers.vehicles.create

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)  // Initial state
    .addSupportedTripTypes(TripType.EXCLUSIVE)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .addAttributes(VehicleAttribute.newBuilder()
        .setKey("on_trip").setValue("false"))  // Opaque to the Fleet Engine
    // Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
    // matching while even if it is on a trip.  By default this is disabled.
    .build();

CreateVehicleRequest createVehicleRequest =
    CreateVehicleRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setVehicleId("vid-8241890")  // Vehicle ID assigned by Rideshare or Delivery Provider
        .setVehicle(vehicle)  // Initial state
        .build();

// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided.  When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.

try {
  Vehicle createdVehicle =
      vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle created successfully.

บันทึก Google Cloud Platform สำหรับการสร้างยานพาหนะ

Fleet Engine API จะเขียนรายการบันทึกผ่านบันทึกของ Google Cloud Platform เมื่อได้รับการเรียกใช้ไปยังปลายทาง CreateVehicle รายการบันทึกจะมีข้อมูลเกี่ยวกับค่าในคำขอ CreateVehicle หากการโทรประสบความสำเร็จ จะมีข้อมูลเกี่ยวกับ Vehicle ที่ส่งคืนด้วย

Shell

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'

ควรพิมพ์ระเบียนในลักษณะต่อไปนี้

---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
  '@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
  request:
    vehicle:
      attributes:
      - key: on_trip
        value: 'false'
      maximumCapacity: 4
      state: VEHICLE_STATE_OFFLINE
      supportedTrips:
      - EXCLUSIVE_TRIP
      vehicleType:
        vehicleCategory: AUTO
    vehicleId: vid-8241890
  response:
    attributes:
    - key: on_trip
      value: 'false'
    availableCapacity: 4
    currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
    maximumCapacity: 4
    name: providers/project-id/vehicles/vid-8241890
    state: VEHICLE_STATE_OFFLINE
    supportedTrips:
    - EXCLUSIVE_TRIP
    vehicleType:
      vehicleCategory: AUTO
labels:
  vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
  labels:
    location: global
    resource_container: projects/project-id
  type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'

การแจ้งเตือน Cloud Pub/Sub สำหรับการสร้างยานพาหนะ

Fleet Engine API จะเผยแพร่การแจ้งเตือนผ่าน Cloud Pub/Sub เมื่อมีการสร้างยานพาหนะใหม่ หากต้องการรับการแจ้งเตือนเหล่านี้ โปรดทำตามวิธีการที่นี่

วิธีการ: อัปเดตตำแหน่งของรถ

หากไม่ได้ใช้ Driver SDK เพื่ออัปเดตตำแหน่งของรถ คุณโทรหา Fleet Engine ได้โดยตรงพร้อมระบุตำแหน่งของรถ สำหรับยานพาหนะที่ใช้งานอยู่ Fleet Engine คาดว่าจะอัปเดตตำแหน่งอย่างน้อย 1 ครั้งทุกนาทีและสูงสุด 1 ครั้งทุก 5 วินาที การอัปเดตเหล่านี้ต้องการเฉพาะผู้ใช้ Fleet Engine Driver SDK

ตัวอย่าง

Shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
}
EOM

ดูข้อมูลอ้างอิง providers.vehicles.update

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setLastLocation(VehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("last_location"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

วิธีการ: อัปเดตช่องยานพาหนะอื่นๆ

การอัปเดตแอตทริบิวต์อื่นๆ ของสถานะของยานพาหนะจะเกิดขึ้นน้อยกว่าการอัปเดตตำแหน่ง การอัปเดตแอตทริบิวต์อื่นที่ไม่ใช่ last_location ต้องใช้สิทธิ์ของผู้ใช้ขั้นสูงของ Fleet Engine

UpdateVehicleRequest จะมี update_mask เพื่อระบุว่าควรอัปเดตช่องใด ลักษณะการทำงานของช่องนี้เหมือนกับในเอกสาร Protobuf สำหรับมาสก์ฟิลด์

ตามที่ระบุไว้ในแอตทริบิวต์ยานพาหนะ การอัปเดตช่อง attributes จะต้องมีการเขียนแอตทริบิวต์ทั้งหมดไว้ คุณจะอัปเดตค่าของคู่คีย์-ค่าเพียงคู่เดียวในการเรียกใช้ UpdateVehicle ไม่ได้ หากต้องการอัปเดตค่าของแอตทริบิวต์ที่เจาะจง ให้ใช้ API ของ UpdateVehicleAttributes

ตัวอย่าง

ตัวอย่างนี้เปิดใช้ back_to_back

Shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "on_trip", "value": "true"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

ดูข้อมูลอ้างอิง providers.vehicles.update

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_state")
        .addPaths("attributes")
        .addPaths("back_to_back_enabled"))
    .build();

// Attributes and vehicle state are being updated, so both are
// included in the field mask.  Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

บันทึกของ Google Cloud Platform สำหรับการอัปเดตยานพาหนะ

Fleet Engine API จะเขียนรายการบันทึกผ่านบันทึกของ Google Cloud Platform เมื่อได้รับการเรียกใช้ไปยังปลายทาง UpdateVehicle รายการบันทึกจะมีข้อมูลเกี่ยวกับค่าในคำขอ UpdateVehicle หากการโทรประสบความสำเร็จ จะมีข้อมูลเกี่ยวกับ Vehicle ที่ส่งคืนด้วย

Shell

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'

การแจ้งเตือน Cloud Pub/Sub สำหรับการอัปเดตยานพาหนะ

Fleet Engine API เผยแพร่การแจ้งเตือนผ่าน Cloud Pub/Sub เมื่อมีการอัปเดตยานพาหนะที่มีอยู่ หากต้องการรับการแจ้งเตือนเหล่านี้ โปรดทำตามวิธีการที่นี่

วิธีการ: ค้นหายานพาหนะ

Fleet Engine รองรับการค้นหายานพาหนะ SearchVehicles API ช่วยคุณค้นหาคนขับรถในบริเวณใกล้เคียงที่เหมาะที่สุดกับงาน เช่น การให้บริการเรียกรถหรือคำขอส่งรถ SearchVehicles API จะแสดงรายการนักขับที่ได้รับการจัดอันดับที่ตรงกับแอตทริบิวต์ของงานกับแอตทริบิวต์ของยานพาหนะในกองยานพาหนะของคุณ ดูข้อมูลเพิ่มเติมได้ที่การค้นหาผู้ขับขี่ที่อยู่ใกล้เคียง

ตัวอย่าง

เมื่อค้นหายานพาหนะที่ใช้ได้ Fleet Engine จะยกเว้นยานพาหนะในการเดินทางที่ดำเนินอยู่โดยค่าเริ่มต้น บริการของบริการเรียกรถหรือผู้ให้บริการจัดส่งต้องรวมบริการเหล่านั้นไว้ในคำขอการค้นหาอย่างชัดเจน ตัวอย่างต่อไปนี้แสดงวิธีรวมยานพาหนะเหล่านั้นในการค้นหายานพาหนะที่ตรงกับการเดินทางจากศูนย์การค้า Grand Indonesia East Mall ไปยังศูนย์ประชุม Balai Sidang Jakarta Convention Center

Shell

ก่อนอื่นให้อัปเดตตำแหน่งของยานพาหนะที่เราสร้างในขั้นตอนก่อนหน้าเพื่อให้มีสิทธิ์ ในความเป็นจริง จะเป็นการใช้ Driver SDK ที่ทำงานบนอุปกรณ์ Android หรือ iOS ในรถ

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
    "location": {
      "latitude": "-6.195139",
      "longitude": "106.820826"
    }
  },
  "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

การค้นหาควรให้ผลลัพธ์เป็นยานพาหนะดังกล่าวเป็นอย่างน้อย

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  },
  "pickupRadiusMeters": 2000,
  "count": 10,
  "minimumCapacity": 2,
  "tripTypes": ["EXCLUSIVE"],
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
  "orderBy": "PICKUP_POINT_ETA",
  "includeBackToBack": true
}
EOM

ดูข้อมูลอ้างอิง providers.vehicles.search

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jakarta Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);

  // Search results: Each vehicle match contains a vehicle entity and information
  // about the distance and ETA to the pickup point and dropoff point.
  List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

การค้นหาการกรองยานพาหนะ

SearchVehicles และ ListVehicles รองรับการกรองในแอตทริบิวต์ยานพาหนะ โดยใช้คำค้นหาตัวกรอง ดูตัวอย่างไวยากรณ์การค้นหาตัวกรองได้ที่ AIP-160

โปรดทราบว่าการค้นหาตัวกรองรองรับเฉพาะการกรองแอตทริบิวต์ยานพาหนะเท่านั้น และใช้กับฟิลด์อื่นๆ ไม่ได้ การค้นหาของตัวกรองทำหน้าที่เป็นอนุประโยค AND ที่มีข้อจำกัดอื่นๆ เช่น minimum_capacity หรือ vehicle_types ใน SearchVehiclesRequest

วิธีการ: แสดงรายการยานพาหนะ

SearchVehicles ได้รับการเพิ่มประสิทธิภาพให้การค้นหายานพาหนะไม่กี่คันที่อยู่ในลำดับสูงได้อย่างรวดเร็วมาก และจะใช้เพื่อค้นหาผู้ขับขี่ที่อยู่ใกล้เคียงที่เหมาะกับงานมากที่สุด อย่างไรก็ตาม บางครั้งคุณอาจต้องค้นหายานพาหนะทั้งหมดที่เป็นไปตามเกณฑ์ แม้ว่าจะจำเป็นต้องดูหน้าผลลัพธ์ก็ตาม ListVehicles ออกแบบมาสำหรับกรณีการใช้งานดังกล่าว

ListVehicles API ช่วยให้คุณค้นหายานพาหนะทั้งหมดที่เป็นไปตามตัวเลือกคำขอบางรายการได้ ListVehicles API จะแสดงรายการยานพาหนะในโปรเจ็กต์ที่มีเลขหน้าซึ่งตรงกับข้อกำหนดบางรายการ

หากต้องการกรองแอตทริบิวต์ยานพาหนะ โปรดดูคำค้นหาการกรองยานพาหนะ

ตัวอย่าง

ตัวอย่างนี้จะทำการกรอง vehicle_type และแอตทริบิวต์โดยใช้สตริง filter

Shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
}
EOM

ดูข้อมูลอ้างอิง providers.vehicles.list

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
    .setParent(parent)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  ListVehiclesResponse listVehiclesResponse =
      vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

การเดินทางและวงจรชีวิต

Trip API และวงจรคล้ายกับยานพาหนะ API และวงจร ผู้ให้บริการ Rideshare มีหน้าที่สร้างการเดินทางโดยใช้อินเทอร์เฟซ Fleet Engine Fleet Engine มีทั้งบริการ RPC, TripService และทรัพยากร REST provider.trips อินเทอร์เฟซเหล่านี้ช่วยให้สร้างเอนทิตี Trip คำขอข้อมูล ฟังก์ชันการค้นหา และความสามารถในการอัปเดต

Trip มีช่องสถานะสำหรับติดตามความคืบหน้าในวงจร ค่าจะย้ายจาก NEW ไปยัง COMPLETE บวก CANCELED และ UNKNOWN_TRIP_STATUS โปรดดู trip_status สำหรับ RPC หรือ TripStatus สำหรับ REST

  • NEW
  • ENROUTE_TO_PICKUP
  • ARRIVED_AT_PICKUP
  • ENROUTE_TO_INTERMEDIATE_DESTINATION
  • ARRIVED_AT_INTERMEDIATE_DESTINATION
  • ENROUTE_TO_DROPOFF
  • COMPLETE

บริการของคุณสามารถอัปเดตการเดินทางไปยัง CANCELED จากสถานะใดก็ได้เหล่านี้ เมื่อบริการสร้างการเดินทาง เครื่องมือจะตั้งค่าสถานะเป็น NEW คุณจะป้อน vehicle_id หรือไม่ก็ได้ เช่นเดียวกับยานพาหนะ บริการจะลบการเดินทางโดยอัตโนมัติหลังจาก 7 วันโดยไม่มีการอัปเดต หากบริการพยายามสร้างการเดินทางด้วยรหัสที่มีอยู่แล้ว ระบบจะแสดงข้อผิดพลาด การเดินทางจะถือว่า "ใช้งานอยู่" หากการเดินทางอยู่ในสถานะอื่นที่ไม่ใช่ COMPLETE หรือ CANCELED ความแตกต่างนี้สําคัญในช่อง active_trips ในเอนทิตียานพาหนะและ SearchTripsRequest

บริการจะเปลี่ยน vehicle_id ที่กำหนดให้กับการเดินทางได้เท่านั้นเมื่อการเดินทางทำงานอยู่ ตัวอย่างเช่น คุณจะดำเนินการนี้เมื่อคนขับยกเลิกการเดินทางในระหว่าง เส้นทางและมีการเปลี่ยนการเดินทางไปยังรถคันอื่น

สถานะมีความสำคัญเมื่อใช้การสนับสนุนการเดินทางกลับไป การรองรับนี้จะช่วยให้ผู้ให้บริการกำหนดเส้นทางใหม่ไปยังยานพาหนะในขณะที่ยานพาหนะนั้นอยู่ระหว่างการเดินทางได้ รหัสสำหรับการสร้างการเดินทางขากลับจะเหมือนกับการเดินทางครั้งเดียว และใช้รหัสพาหนะเดียวกัน Fleet Engine จะเพิ่มต้นทางและจุดหมายของการเดินทางใหม่ไปยังจุดอ้างอิงของยานพาหนะ ดูข้อมูลเพิ่มเติมเกี่ยวกับการเดินทางไป-กลับได้ที่สร้างการเดินทางหลายจุดระหว่างทาง

จุดอ้างอิงที่เหลือของการเดินทาง

เอนทิตีการเดินทางมีช่อง TripWaypoint ที่ซ้ำ (RPC | REST) ซึ่งเรียกว่า remainingWaypoints(RPC | REST) ช่องนี้ระบุจุดอ้างอิงทั้งหมดที่ยานพาหนะจะต้องเดินทางตามลำดับก่อนถึงจุดลงจอดสุดท้ายของการเดินทางนี้ ระบบจะคำนวณจาก จุดอ้างอิงที่เหลือของยานพาหนะ ในกรณีการใช้งาน "กลับไปขาไป" และ "การโดยสารรถร่วมกัน" รายการนี้มีจุดอ้างอิงจากการเดินทางอื่นๆ ที่จะข้ามผ่านก่อนการเดินทางนี้ แต่ไม่รวมจุดอ้างอิงหลังจากการเดินทางครั้งนี้ จุดอ้างอิงในรายการระบุได้ด้วย TripId และ WaypointType

ความสัมพันธ์ระหว่างสถานะการเดินทางกับจุดอ้างอิงที่เหลืออยู่ของยานพาหนะ

ระบบจะอัปเดตจุดอ้างอิงที่เหลือของยานพาหนะ (RPC | REST) เมื่อ Fleet Engine ได้รับคำขอเปลี่ยนสถานะการเดินทาง ระบบจะนำจุดอ้างอิงก่อนหน้าออกจากรายการจุดอ้างอิงที่เหลือของยานพาหนะเมื่อ tripStatus(RPC | REST) เปลี่ยนจากสถานะอื่นเป็น ENROUTE_TO_XXX นั่นก็คือ เมื่อสถานะการเดินทางเปลี่ยนจาก ENROUTE_TO_PICKUP เป็น ARRIVED_AT_PICKUP จุดรับของการเดินทางจะยังคงอยู่ในรายการจุดอ้างอิงที่เหลืออยู่ของยานพาหนะ แต่เมื่อสถานะการเดินทางเปลี่ยนเป็น ENROUTE_TO_INTERMEDIATE_DESTINATION หรือ ENROUTE_TO_DROPOFF จุดรับของการเดินทางจะถูกนำออกจากจุดหมายที่เหลืออยู่ของรถ

คือเหมือนกันสำหรับ ARRIVED_AT_INTERMEDIATE_DESTINATION และ ENROUTE_TO_INTERMDEDIATE_DESTINATION เมื่อ ARRIVED_AT_INTERMEDIATE_DESTINATION จุดหมายกลางปัจจุบันจะไม่ถูกนำออกจากรายการจุดอ้างอิงที่เหลืออยู่ของ ยานพาหนะ จนกว่ายานพาหนะจะรายงานว่ามีการเปลี่ยนเส้นทางไปยังจุดอ้างอิงถัดไป

เมื่อสถานะการเดินทางเปลี่ยนเป็น COMPLETED จะไม่มีจุดอ้างอิงจากการเดินทางนี้ในรายการจุดอ้างอิงที่เหลืออยู่ของยานพาหนะ

วิธีการ: สร้างการเดินทาง

ต้องสร้างเอนทิตี Trip เพื่อให้ระบบติดตามคำขอการเดินทางแต่ละรายการและจับคู่กับยานพาหนะในกองยาน ใช้ปลายทาง CreateTrip กับ CreateTripRequest เพื่อสร้างการเดินทาง

โดยต้องมีแอตทริบิวต์ต่อไปนี้เพื่อสร้างการเดินทาง

  • parent - สตริงที่มีรหัสผู้ให้บริการซึ่งสร้างขึ้นเมื่อสร้างโปรเจ็กต์ Google Cloud
  • trip_id - สตริงที่สร้างโดยผู้ให้บริการบริการร่วมเดินทาง
  • trip - คอนเทนเนอร์ที่มีข้อมูลเมตาพื้นฐานที่อธิบายการเดินทาง
    • trip_type - enum เพื่อบอกว่าการเดินทางอาจมีผู้โดยสารคนอื่นๆ จากต้นทางและจุดหมายอื่นในยานพาหนะเดียวกัน (SHARED) หรือผู้โดยสารคนเดียว (EXCLUSIVE) หรือไม่
    • pickup_point - TerminalLocation แสดงถึงต้นทางของการเดินทาง โปรดดูข้อมูลอ้างอิงของ RPC หรือข้อมูลอ้างอิงของ REST

เมื่อสร้างการเดินทาง ให้ระบุ number_of_passengers, dropoff_point และ vehicle_id แม้ว่าจะไม่จำเป็นต้องกรอกข้อมูลในช่องเหล่านี้ แต่หากคุณระบุ ช่องดังกล่าวจะเก็บไว้ ระบบจะไม่พิจารณาช่อง Trip อื่นๆ ทั้งหมด ตัวอย่างเช่น การเดินทางทั้งหมดจะเริ่มต้นด้วย trip_status เป็น NEW แม้ว่าคุณจะส่งผ่านใน trip_status ของ CANCELED ในคำขอสร้าง

ตัวอย่าง

ตัวอย่างต่อไปนี้ทำให้เกิดการเดินทางไปยังศูนย์การค้า Grand Indonesia East Mall การเดินทางนี้สำหรับผู้โดยสาร 2 คนและเป็นราคาพิเศษ provider_id ของ Trip ต้องเป็นรหัสเดียวกับรหัสโปรเจ็กต์ ในตัวอย่างนี้ ผู้ให้บริการ Rideshare ได้สร้าง โปรเจ็กต์ Google Cloud ซึ่งก็คือ project-id โปรเจ็กต์นี้ต้องมีบัญชีบริการที่ใช้เรียกใช้ Fleet Engine สถานะของการเดินทางคือNEW

หลังจากนั้น หลังจากที่บริการตรงกับการเดินทางไปยังรถแล้ว บริการจะโทรหา UpdateTrip และเปลี่ยน vehicle_id เมื่อมีการเดินทางให้กับยานพาหนะได้

Shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "tripType": "EXCLUSIVE",
  "numberOfPassengers": 2,
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  }
}
EOM

ดูข้อมูลอ้างอิง providers.trips.create

Java

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
    .setPickupPoint(                 // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    // Provide the number of passengers if available.
    .setNumberOfPassengers(2)
    // Provide the drop-off point if available.
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
    .build();

CreateTripRequest createTripRequest =
    CreateTripRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setTripId("tid-1f97")  // Trip ID assigned by the Provider
        .setTrip(trip)              // Initial state
        .build();

// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.

try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

บันทึกของ Google Cloud Platform สำหรับการสร้างการเดินทาง

Fleet Engine API จะเขียนรายการบันทึกโดยใช้บันทึกของ Google Cloud Platform เมื่อได้รับการเรียกใช้ไปยังปลายทาง CreateTrip รายการบันทึกจะมีข้อมูลเกี่ยวกับค่าในคำขอ CreateTrip หากการเรียกสำเร็จ จะมีข้อมูลเกี่ยวกับ Trip ที่ส่งกลับด้วย

วิธีการ: อัปเดตการเดินทาง

เอนทิตีการเดินทางมีช่องที่เปิดใช้การติดตามโดยบริการและการรายงานความคืบหน้าของการเดินทางโดย SDK ไดรเวอร์และไปยัง Consumer SDK หากต้องการอัปเดตพร็อพเพอร์ตี้ ให้ใช้ข้อความ UpdateTripRequest การดำเนินการนี้จะอัปเดตช่องการเดินทางตาม field_mask ของคำขอ โปรดดู UpdateTripRequest

ผู้ให้บริการบริการเรียกรถมีหน้าที่อัปเดตแอตทริบิวต์ต่อไปนี้

  • สถานะการเดินทาง
  • รหัสยานพาหนะ โดยอาจเป็น ณ เวลาที่สร้าง หรือหลังจากจับคู่ยานพาหนะกับการเดินทาง
  • เปลี่ยนเป็นจุดรับ ส่งของ และจุดอ้างอิง

Fleet Engine จะอัปเดตช่องต่อไปนี้โดยอัตโนมัติเมื่อใช้ฟีเจอร์การแชร์เส้นทางผ่าน Driver SDK หรือ Consumer SDK

  • เส้นทาง
  • ETA
  • ระยะทางที่เหลือ
  • ตำแหน่งของรถ
  • จุดอ้างอิงที่เหลือ

โปรดดู Tripใน RPC หรือ Resource.Trip ใน REST

บันทึกของ Google Cloud Platform สำหรับข้อมูลอัปเดตการเดินทาง

Fleet Engine API จะเขียนรายการบันทึกโดยใช้บันทึกของ Google Cloud Platform เมื่อได้รับการเรียกใช้ไปยังปลายทาง UpdateTrip รายการบันทึกจะมีข้อมูลเกี่ยวกับค่าในคำขอ UpdateTrip หากเรียกใช้สำเร็จ จะมีข้อมูลเกี่ยวกับ Trip ที่แสดงผลด้วย

HOW-TO: ค้นหาการเดินทาง

Fleet Engine รองรับการค้นหาการเดินทาง ตามที่ได้แจ้งไว้ก่อนหน้านี้ ระบบจะลบทริปโดยอัตโนมัติหลังจากผ่านไป 7 วัน ดังนั้น SearchTrips จะไม่แสดงประวัติทั้งหมดของทริป

แม้ว่า SearchTrips จะเป็น API ที่ยืดหยุ่น แต่รายการด้านล่างจะพิจารณากรณีการใช้งาน 2 กรณี

  • การกำหนดการเดินทางที่ใช้งานอยู่ของยานพาหนะ -- ผู้ให้บริการสามารถระบุการเดินทางที่ใช้งานอยู่ในปัจจุบันของยานพาหนะได้ ภายใน SearchTripsRequest ต้องตั้งค่า vehicle_id เป็นยานพาหนะที่อยู่ระหว่างการพิจารณา และควรตั้งค่า active_trips_only เป็น true

  • การปรับยอดผู้ให้บริการกับสถานะของ Fleet Engine -- ผู้ให้บริการใช้ SearchTrips เพื่อให้แน่ใจว่าสถานะของการเดินทางและสถานะของ Fleet Engine ตรงกันได้ ซึ่งสำคัญมากสำหรับ TripStatus หากสถานะของการเดินทางที่กำหนดให้กับยานพาหนะไม่ได้ตั้งค่าเป็น COMPLETE หรือ CANCELED อย่างถูกต้อง SearchVehicles จะไม่รวมยานพาหนะดังกล่าว

หากต้องการใช้ SearchTrips ในลักษณะนี้ ให้ปล่อย vehicle_id ว่างไว้ ตั้งค่า active_trips_only เป็น true และตั้งค่า minimum_staleness ให้นานกว่าระยะเวลาการเดินทางส่วนใหญ่ ตัวอย่างเช่น คุณอาจใช้ 1 ชั่วโมง ผลลัพธ์ประกอบด้วยการเดินทางที่ไม่สมบูรณ์หรือยกเลิก และไม่มีการอัปเดตในกว่า 1 ชั่วโมง ผู้ให้บริการควรตรวจสอบทริปเหล่านี้เพื่อให้แน่ใจว่าสถานะใน Fleet Engine ได้รับการอัปเดตอย่างถูกต้อง

การแก้ปัญหา

ในกรณีที่เกิดข้อผิดพลาด DEADLINE_EXCEEDED ระบบจะไม่ทราบสถานะของ Fleet Engine ผู้ให้บริการควรเรียกใช้ CreateTrip อีกครั้ง ซึ่งจะแสดง 201 (CREATED) หรือ 409 (CONFLICT) ในกรณีหลัง คำขอก่อนหน้าประสบความสำเร็จก่อนวันที่ DEADLINE_EXCEEDED ดูคู่มือ Consumer API สำหรับข้อมูลเพิ่มเติม เกี่ยวกับการจัดการข้อผิดพลาดในการเดินทางได้ที่ Android หรือ iOS

ความช่วยเหลือในการโดยสารรถร่วมกัน

คุณกำหนดการเดินทางSHAREDได้หลายครั้งให้กับยานพาหนะที่รองรับ TripType.SHARED คุณต้องระบุลำดับของจุดอ้างอิงที่ไม่ผ่านทั้งหมดสำหรับการเดินทางทั้งหมดที่กำหนดให้กับรถในการเดินทางร่วมนี้ผ่าน Trip.vehicle_waypoints เมื่อคุณกำหนด vehicle_id สำหรับการเดินทางที่แชร์ร่วมกัน (ในคำขอ CreateTrip หรือ UpdateTrip) โปรดดู vehicle_waypoints สำหรับ RPC หรือ vehicleWaypoints สำหรับ REST

การรองรับปลายทางหลายแห่ง

ระบุปลายทางตัวกลาง

ระบบได้รวมช่อง intermediateDestinations และช่อง intermediateDestinationIndex ในการเดินทาง (RPC | REST) เข้าด้วยกันเพื่อใช้ระบุจุดหมาย

อัปเดตปลายทางระดับกลาง

คุณอัปเดตปลายทางขั้นกลางได้ผ่าน UpdateTrip เมื่ออัปเดตปลายทางขั้นกลาง คุณต้องระบุรายการจุดหมายระดับกลางทั้งหมด รวมถึงปลายทางที่เคยเข้าชม ไม่ใช่แค่เพียงแห่งเดียวที่เพิ่มใหม่หรือที่ต้องแก้ไข เมื่อ intermediateDestinationIndex ชี้ไปยังดัชนีหลังตำแหน่งปลายทางขั้นกลางที่เพิ่ม/แก้ไขใหม่ ระบบจะไม่เพิ่มปลายทางขั้นกลางใหม่/ที่อัปเดตไปยัง waypoints หรือ remainingWaypoints ของการเดินทาง สาเหตุก็คือปลายทางขั้นกลางใดๆ ที่อยู่ก่อน intermediateDestinationIndex จะถือว่าเป็นการเข้าชมแล้ว

การเปลี่ยนแปลงสถานะการเดินทาง

ต้องระบุช่อง intermediateDestinationsVersion ใน (RPC | REST) ในคำขออัปเดตสถานะการเดินทางที่ส่งไปยัง Fleet Engine เพื่อระบุว่าปลายทางระดับกลางได้ผ่านไปแล้ว ปลายทางระดับกลางที่กำหนดเป้าหมาย จะมีการระบุผ่านช่อง intermediateDestinationIndex เมื่อ tripStatus (RPC | REST) คือ ENROUTE_TO_INTERMEDIATE_DESTINATION ตัวเลขระหว่าง [0..N-1] บ่งชี้ถึงจุดหมายกลางที่ยานพาหนะจะขับต่อไป เมื่อ tripStatus คือ ARRIVED_AT_INTERMEDIATE_DESTINATION ตัวเลขระหว่าง [0..N-1] บ่งชี้ถึงจุดหมายระดับกลางที่ยานพาหนะอยู่

ตัวอย่าง

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีอัปเดตสถานะของการเดินทางเพื่อเปลี่ยนเส้นทางไปยังปลายทางกลางแรก โดยสมมติว่าคุณได้สร้างการเดินทางแบบหลายจุดหมาย และการเดินทางผ่านจุดรับสินค้าไปแล้ว

Java

static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to update.
Trip trip = Trip.newBuilder()
    // Trip status cannot go back to a previous status once it is passed
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
    // Enrouting to the first intermediate destination.
    .setIntermediateDestinationIndex(0)
    // intermediate_destinations_version MUST be provided to ensure you
    // have the same picture on intermediate destinations list as FleetEngine has.
    .setIntermediateDestinationsVersion(
        trip.getIntermediateDestinationsVersion())
    .build();

// Trip update request
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(
            FieldMask.newBuilder()
                .addPaths("trip_status")
                .addPaths("intermediate_destination_index")
                // intermediate_destinations_version must not be in the
                // update mask.
                .build())
        .build();

// Error handling
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:  // Trip does not exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid, or the
                                // intermediate_destinations_version
                                // doesn’t match FleetEngine’s.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

วิธีการ: สมัครรับข้อความแจ้งเตือนจาก Fleet Engine API

Fleet Engine API ใช้ Google Cloud Pub/Sub เพื่อเผยแพร่การแจ้งเตือนในหัวข้อที่สร้างโดยโปรเจ็กต์ Google Cloud สำหรับผู้บริโภค Pub/Sub ไม่ได้เปิดใช้โดยค่าเริ่มต้นสำหรับ Fleet Engine ในโปรเจ็กต์ Google Cloud ของคุณ โปรดส่งเคสขอรับความช่วยเหลือหรือติดต่อวิศวกรลูกค้าเพื่อเปิดใช้ Pub/Sub

หากต้องการสร้างหัวข้อในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ ให้ทำตามวิธีการเหล่านี้ รหัสหัวข้อต้องเป็น "fleet_engine_notifications"

คุณต้องสร้างหัวข้อในโปรเจ็กต์ Cloud เดียวกับที่เรียกใช้ API ของ Fleet Engine

เมื่อสร้างหัวข้อแล้ว คุณจะต้องให้สิทธิ์ Fleet Engine API เพื่อเผยแพร่ในหัวข้อดังกล่าว วิธีการคือคลิกหัวข้อ ที่คุณเพิ่งสร้างขึ้น แล้วเพิ่มสิทธิ์ใหม่ คุณอาจต้องคลิกแสดงแผงข้อมูลเพื่อเปิดเครื่องมือแก้ไขสิทธิ์ ผู้ใช้หลักควรเป็น geo-fleet-engine@system.gserviceaccount.com และบทบาทควรเป็น Pub/Sub publisher

หากต้องการตั้งค่าโปรเจ็กต์ที่อยู่ในระบบคลาวด์ให้สมัครรับการแจ้งเตือน โปรดทำตามวิธีการเหล่านี้

Fleet Engine API จะเผยแพร่การแจ้งเตือนแต่ละรายการในรูปแบบข้อมูลที่แตกต่างกัน 2 รูปแบบ ได้แก่ protobuf และ json รูปแบบข้อมูลสำหรับการแจ้งเตือนแต่ละรายการจะแสดงอยู่ในแอตทริบิวต์ PubsubMessage โดยมีคีย์เป็น data_format และค่าเป็น protobuf หรือ json

สคีมาการแจ้งเตือน:

โปรโตคอล

// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
  // Required. At least one notification must exist.
  // List of notifications containing information related to changes in
  // Fleet Engine data.
  repeated Notification notifications = 1;
}

// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
  // Required. At least one type must exist.
  // Type of notification.
  oneof type {
    // Notification related to changes in vehicle data.
    VehicleNotification vehicle_notification = 1;
  }
}

// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
  // Required.
  // Vehicle must contain all fields that were set when it was created.
  Vehicle vehicle = 1;
}

// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
  // Required.
  // Vehicle must only contain name and fields that are present in the
  // field_mask field below.
  Vehicle vehicle = 1;

  // Required.
  // Contains vehicle field paths that were specifically requested
  // by the Provider.
  google.protobuf.FieldMask field_mask = 2;
}

// Notification related to changes in vehicle data.
message VehicleNotification {
  // Required. At least one type must be set.
  // Type of notification.
  oneof type {
    // Notification sent when a new vehicle was created.
    CreateVehicleNotification create_notification = 1;
    // Notification sent when an existing vehicle is updated.
    UpdateVehicleNotification update_notification = 2;
  }
}

JSON

BatchNotification: {
  "description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
  "type": "object",
  "required": ["notifications"],
  "properties": {
    "notifications": {
      "description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
      "type": "Notification[]"
    }
  }
}

Notification: {
  "description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
  "type": "object",
  "properties": {
    "vehicleNotification": {
      "description": "Notification related to changes in vehicle data.",
      "type": "VehicleNotification"
    }
  }
}

VehicleNotification: {
  "description": "Notification related to changes in vehicle data.",
  "type": "object",
  "properties": {
    "createNotification": {
      "description": "Notification sent when a new vehicle was created.",
      "type": "CreateVehicleNotification"
    },
    "updateNotification": {
      "description": "Notification sent when an existing vehicle is updated.",
      "type": "UpdateVehicleNotification"
    }
  }
}

CreateVehicleNotification: {
  "description": "Notification sent when a new vehicle was created.",
  "type": "object",
  "required": ["vehicle"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must contain all fields that were set when it was created.",
      "type": "Vehicle"
    }
  }
}

UpdateVehicleNotification: {
  "description": "Notification sent when an existing vehicle is updated.",
  "type": "object",
  "required": ["vehicle", "fieldMask"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
      "type": "Vehicle"
    },
    "fieldMask": {
      "description": "Contains vehicle field paths that were specifically requested by the Provider.",
      "type": "FieldMask"
    }
  }
}