फ़्लीट इंजन का इस्तेमाल शुरू करना

Fleet Engine की मांग पर मिलने वाली राइड और डिलीवरी एपीआई से, आपको यात्रा और ऑर्डर की स्थिति वाले ऐप्लिकेशन के लिए, यात्रा और वाहन की स्थिति मैनेज करने की सुविधा मिलती है. यह ड्राइवर SDK टूल, उपभोक्ता SDK टूल, और आपकी बैकएंड सेवा के बीच लेन-देन को मैनेज करता है. ये gRPC या REST कॉल करके, Fleet Engine से संपर्क कर सकते हैं.

ज़रूरी शर्तें

डेवलपमेंट के लिए, पक्का करें कि आपने Cloud SDK टूल इंस्टॉल करें (gcloud) और आपके प्रोजेक्ट के लिए पुष्टि की गई है.

शेल

gcloud auth login

आपको सफल होने का मैसेज दिखेगा, जैसे कि:

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

देखें कि मांग पर राइड और डिलीवरी सलूशन फ़्लीट इंजन एपीआई को सही तरीके से कॉन्फ़िगर किया गया है या नहीं.

शेल

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

अगर इस निर्देश से कोई गड़बड़ी होती है, तो ऐक्सेस पाने के लिए अपने प्रोजेक्ट एडमिन और Google सहायता प्रतिनिधि से संपर्क करें.

लॉगिंग

Fleet Engine, उसे मिलने वाले एपीआई कॉल के बारे में Google Cloud Platform के लॉग में लॉग मैसेज लिख सकता है. लॉग पढ़ने और उनका विश्लेषण करने के तरीके की खास जानकारी पाने के लिए, क्लाउड लॉगिंग दस्तावेज़ देखें.

हो सकता है कि 10 फ़रवरी, 2022 से पहले बनाए गए प्रोजेक्ट के लिए, डेटा लॉग करने की सुविधा डिफ़ॉल्ट रूप से चालू न हो. ज़्यादा जानकारी के लिए, लॉगिंग दस्तावेज़ देखें.

क्लाइंट लाइब्रेरी

हम क्लाइंट लाइब्रेरी को कई सामान्य प्रोग्रामिंग भाषाओं में पब्लिश करते हैं. ये लाइब्रेरी, रॉ REST या gRPC के मुकाबले, डेवलपर को बेहतर अनुभव देने में मदद करेंगी. अपने सर्वर ऐप्लिकेशन के लिए क्लाइंट लाइब्रेरी पाने के तरीके से जुड़े निर्देशों के लिए, क्लाइंट लाइब्रेरी देखें.

इस दस्तावेज़ में दिए गए Java उदाहरण gRPC से परिचित हैं.

पुष्टि करना और अनुमति देना

Google Cloud Console के ज़रिए, यात्रा और ऑर्डर की प्रोग्रेस से जुड़ी सुविधाओं को कॉन्फ़िगर किया जा सकता है. इन एपीआई और SDK टूल को ऐसे JSON वेब टोकन की ज़रूरत होती है जिन्हें Cloud Console से बनाए गए सेवा खातों का इस्तेमाल करके साइन किया गया हो.

Cloud प्रोजेक्ट का सेटअप

अपना क्लाउड प्रोजेक्ट सेट अप करने के लिए, पहले अपना प्रोजेक्ट बनाएं. इसके बाद, सेवा खाते बनाएं.

Google Cloud प्रोजेक्ट बनाने के लिए:

  1. Google Cloud Console का इस्तेमाल करके, Google Cloud प्रोजेक्ट बनाएं.
  2. एपीआई और सेवा डैशबोर्ड का इस्तेमाल करके, Local Rides and डिलीवरी API को चालू करें.

सेवा खाते एक या उससे ज़्यादा भूमिकाओं से जुड़े होते हैं. इनका इस्तेमाल JSON वेब टोकन बनाने के लिए किया जाता है, जो भूमिकाओं के हिसाब से अलग-अलग तरह की अनुमतियां देते हैं. आम तौर पर, गलत इस्तेमाल की संभावना को कम करने के लिए, कई सेवा खाते बनाए जा सकते हैं. हर खाते में, उपयोगकर्ताओं के लिए कम से कम भूमिकाएं होनी चाहिए.

यात्रा और ऑर्डर की स्थिति में इन भूमिकाओं का इस्तेमाल किया जाता है:

भूमिकाकंपनी का ब्यौरा
Fleet Engine उपभोक्ता SDK टूल का उपयोगकर्ता

roles/fleetengine.consumerSdkUser
वाहन खोजने और वाहनों और यात्राओं के बारे में जानकारी पाने की अनुमति देती है. इस भूमिका वाले सेवा खाते से बनाए गए टोकन, आम तौर पर आपके राइडशेयरिंग या डिलीवरी उपभोक्ता ऐप्लिकेशन के मोबाइल डिवाइसों से इस्तेमाल किए जाते हैं.
फ़्लीट इंजन ड्राइवर SDK टूल का उपयोगकर्ता

roles/fleetengine.driverSdkUser
वाहन की जगह और रास्तों को अपडेट करने और वाहनों और यात्राओं की जानकारी पाने की अनुमति देती है. इस भूमिका वाले सेवा खाते से बनाए गए टोकन, आम तौर पर आपके राइडशेयरिंग या डिलीवरी ड्राइवर ऐप्लिकेशन के मोबाइल डिवाइसों से इस्तेमाल किए जाते हैं.
फ़्लीट इंजन ऑन-डिमांड एडमिन

roles/fleetengine.ondemandAdmin
वाहन और यात्रा से जुड़े सभी संसाधनों के लिए, कॉन्टेंट पढ़ने और उसमें बदलाव करने की अनुमति देता है. इस भूमिका वाले प्रिंसिपल को JWT का इस्तेमाल करने की ज़रूरत नहीं है. इसके बजाय, उन्हें ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल का इस्तेमाल करना चाहिए. कस्टम JWT दावों को अनदेखा कर दिया जाता है. यह भूमिका भरोसेमंद एनवायरमेंट (कस्टमर बैकएंड) तक सीमित होनी चाहिए.
Fleet Engine सेवा का सुपर उपयोगकर्ता **(रोक दी गई)**

roles/fleetengine.serviceSuperUser
सभी वाहनों और यात्राओं के एपीआई के लिए अनुमति देता है. इस भूमिका वाले सेवा खाते से बनाए गए टोकन, आम तौर पर आपके बैकएंड सर्वर से इस्तेमाल किए जाते हैं. यह भूमिका अब काम नहीं करती. इसके बजाय, roles/fleetengine.ondemandAdmin को प्राथमिकता दें.

उदाहरण के लिए, तीनों भूमिकाओं में से हर एक के लिए सेवा खाता बनाएं और उन्हें उनसे जुड़ी भूमिकाएं असाइन करें.

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

ड्राइवर और उपभोक्ता के 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 API के ऐक्सेस पर पाबंदी लगाने के लिए, Fleet Engine JSON वेब टोकन (JWTs) का इस्तेमाल करता है. नई Fleet Engine Auth Library, GitHub पर उपलब्ध है. इससे, Fleet Engine JWT बनाने और उन्हें सुरक्षित तरीके से साइन करने में मदद मिलती है.

इस लाइब्रेरी से ये फ़ायदे मिलते हैं:

  • फ़्लीट इंजन टोकन बनाने की प्रोसेस को आसान बनाता है.
  • क्रेडेंशियल फ़ाइलों का इस्तेमाल करने के अलावा, टोकन पर हस्ताक्षर करने के दूसरे तरीके उपलब्ध कराता है (जैसे, किसी सेवा खाते के नाम पर काम करना.)
  • gRPC स्टब या GAPIC क्लाइंट से किए गए आउटबाउंड अनुरोधों के साथ, साइन किए गए टोकन अटैच करता है.

अनुमति देने के लिए JSON वेब टोकन (JWT) बनाया जा रहा है

फ़्लीट इंजन ऑथराइज़ेशन लाइब्रेरी का इस्तेमाल न करने पर, JSON वेब टोकन (JWT) सीधे आपके कोड बेस में तैयार किए जाने चाहिए. इसके लिए, आपको JWT के बारे में अच्छी तरह समझना होगा. साथ ही, आपको यह भी समझना होगा कि ये Fleet Engine से कैसे जुड़े हैं. इसलिए, हम Fleet Engine ऑथराइज़ेशन लाइब्रेरी का इस्तेमाल करने का सुझाव देते हैं.

Fleet Engine में, JSON Web Tokens (JWTs), कुछ समय के लिए पुष्टि करने की सुविधा देता है. साथ ही, यह पक्का करता है कि डिवाइस सिर्फ़ उन वाहनों, यात्राओं या टास्क में बदलाव करें जिनके लिए उन्हें अनुमति मिली हुई है. JWT में एक हेडर और एक दावा सेक्शन होता है. हेडर सेक्शन में जानकारी शामिल होती है. जैसे, इस्तेमाल करने के लिए निजी पासकोड (सेवा खातों से मिलने वाली निजी कुंजी) और एन्क्रिप्ट (सुरक्षित) करने का एल्गोरिदम. दावे वाले सेक्शन में, टोकन बनाने का समय, बने रहने का टोकन, और ऐक्सेस का दावा करने वाली सेवाओं की जानकारी होती है. साथ ही, ऐक्सेस को कम करने के लिए अनुमति से जुड़ी अन्य जानकारी भी होती है. उदाहरण के लिए, वाहन का आईडी.

JWT हेडर सेक्शन में ये फ़ील्ड होते हैं:

फ़ील्डकंपनी का ब्यौरा
alg इस्तेमाल किया जाने वाला एल्गोरिदम. `RS256`.
typ टोकन किस तरह का है. `JWT`.
बच्चा आपके सेवा खाते का निजी कुंजी आईडी. यह वैल्यू, आपके सेवा खाते की JSON फ़ाइल के `private_key_id` फ़ील्ड में देखी जा सकती है. पक्का करें कि उस सेवा खाते की कुंजी का इस्तेमाल किया जा रहा हो जिसके पास सही लेवल की अनुमतियां हैं.

JWT के दावे वाले सेक्शन में ये फ़ील्ड होते हैं:

फ़ील्डकंपनी का ब्यौरा
है आपके सेवा खाते का ईमेल पता.
बदले में खेलने वाला खिलाड़ी आपके सेवा खाते का ईमेल पता.
ऑड आपके सेवा खाते का Service_NAME, इस मामले में https://fleetengine.googleapis.com/
Iat टोकन बनाए जाने के समय का टाइमस्टैंप, जिसे 1 जनवरी, 1970 को 00:00:00 यूटीसी के बाद, बीत चुके सेकंड में बताया गया है. स्क्यू के लिए 10 मिनट दें. अगर टाइमस्टैंप बहुत पहले का या आने वाले समय का है, तो सर्वर कोई गड़बड़ी रिपोर्ट कर सकता है.
exp टोकन की समयसीमा खत्म होने के बाद का टाइमस्टैंप, जिसे 1 जनवरी, 1970 को 00:00:00 यूटीसी के बाद, बीत चुके सेकंड में बताया गया है. अगर टाइमस्टैंप के लिए, आने वाले समय के एक घंटे से ज़्यादा का समय है, तो अनुरोध पूरा नहीं किया जा सकता.
अनुमति देना इस्तेमाल के उदाहरण के आधार पर, इसमें `वाहन आईडी` या `ट्रिपिड` हो सकता है.

JWT टोकन बनाने का मतलब है कि इस पर हस्ताक्षर करना. JWT बनाने और साइन करने के निर्देश और कोड सैंपल के लिए, OAuth के बिना सेवा खाते की अनुमति देना देखें. इसके बाद, gRPC कॉल में साइन किया गया टोकन या Fleet Engine को ऐक्सेस करने के लिए इस्तेमाल किए जाने वाले अन्य तरीकों को अटैच किया जा सकता है.

JWT दावे

JWT पेलोड बनाते समय, अनुमति देने वाले सेक्शन में एक और दावा जोड़ें. इसके लिए, vehicleid या tripid कुंजी को उस वाहन आईडी या ट्रिप आईडी की वैल्यू पर सेट करें जिसके लिए कॉल किया जा रहा है.

ड्राइवर 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"
   }
}

नीचे Driver ऐप्लिकेशन के टोकन का उदाहरण दिया गया है:

{
  "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 फ़ील्ड के लिए, अपने सेवा खाते का निजी कुंजी आईडी बताएं. आपको यह वैल्यू अपने सेवा खाते की JSON फ़ाइल के private_key_id फ़ील्ड में दिखेगी.
  • iss और sub फ़ील्ड के लिए, अपने सेवा खाते का ईमेल पता बताएं. आपको यह वैल्यू अपने सेवा खाते की JSON फ़ाइल के client_email फ़ील्ड में दिखेगी.
  • aud फ़ील्ड के लिए, https://SERVICE_NAME/ बताएं.
  • iat फ़ील्ड के लिए, टोकन बनाए जाने के समय के टाइमस्टैंप का इस्तेमाल करें. यह टाइमस्टैंप 1 जनवरी, 1970 को 00:00:00 यूटीसी के बाद 00:00:00 यूटीसी के बाद, बचे हुए सेकंड के तौर पर बताया जाता है. स्क्यू के लिए 10 मिनट दें. अगर टाइमस्टैंप बहुत पहले का या आने वाले समय का है, तो सर्वर कोई गड़बड़ी रिपोर्ट कर सकता है.
  • exp फ़ील्ड के लिए, टोकन की समयसीमा खत्म होने के टाइमस्टैंप का इस्तेमाल करें. यह टाइमस्टैंप 1 जनवरी, 1970 को 00:00:00 यूटीसी से सेकंड के तौर पर दिखाया जाता है. ज़्यादा से ज़्यादा iat + 3,600 वैल्यू का इस्तेमाल किया जा सकता है.

किसी मोबाइल डिवाइस को पास किए जाने वाले JWT पर साइन करते समय, ड्राइवर या उपभोक्ता 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 के बाद के सेकंड में खत्म होने का समय होती है. इसका हिसाब, iat में 3600 जोड़कर लगाया जा सकता है. एक घंटे से ज़्यादा नहीं हो सकता.

{
  "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

हस्ताक्षर किया गया Base64-कोड में बदला गया JWT अब फ़ाइल signed_token.jwt में सेव होना चाहिए. यह टोकन अगले एक घंटे के लिए मान्य है.

अब वाहनों की सूची वाले REST एंडपॉइंट पर curl कमांड चलाकर, टोकन की जांच की जा सकती है:

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

वाहन और उनका लाइफ़साइकल

वाहन एक ऐसी इकाई है जो ड्राइवर और वाहन के जोड़े के बारे में बताती है. फ़िलहाल, एक ड्राइवर और वाहन को अलग-अलग ट्रैक नहीं किया जा सकता. राइडशेयर या डिलीवरी की सेवा देने वाली कंपनी, सेवा देने वाली कंपनी का आईडी और राइडशेयर या डिलीवरी की सेवा देने वाली कंपनी के मालिकाना हक वाले वाहन का आईडी Google Cloud प्रोजेक्ट के प्रोजेक्ट आईडी के साथ मेल खानी चाहिए. इसमें वह सेवा खाता भी शामिल होता है जिसका इस्तेमाल Fleet Engine API को करने के लिए किया जाता है.

जिस वाहन को UpdateVehicle के ज़रिए अपडेट नहीं किया जाता है वह सात दिन के बाद भी अपने-आप मिट जाएगी. पहले से मौजूद कंपनी के आईडी/वाहन के आईडी के जोड़े का इस्तेमाल करके, CreateVehicle को कॉल करते समय गड़बड़ी हुई. जिन वाहनों का डेटा बार-बार अपडेट नहीं किया जाता है उन्हें इन दो तरीकों से ठीक किया जा सकता है: सेवा देने वाली कंपनी के आईडी/वाहन के आईडी के साथ बार-बार CreateVehicle को कॉल करना और अगर वाहन पहले से मौजूद है, तो गड़बड़ी को खारिज करना है या UpdateVehicle के बाद NOT_FOUND गड़बड़ी के साथ CreateVehicle को कॉल करना है.

वाहन की जगह की जानकारी के अपडेट

Fleet Engine की सबसे अच्छी परफ़ॉर्मेंस के लिए, इसे वाहन की जगह की जानकारी का स्ट्रीम अपडेट दें. ये अपडेट देने के लिए, इनमें से किसी भी तरीके का इस्तेमाल करें:

  1. ड्राइवर SDK टूल - Android, iOS -- सबसे आसान विकल्प इस्तेमाल करें.
  2. कस्टम कोड का इस्तेमाल करें -- यह तब फ़ायदेमंद होता है, जब जगहों को आपके बैकएंड के ज़रिए भेजा जाता है या अगर आप Android या iOS के अलावा किसी दूसरे डिवाइस का इस्तेमाल करते हैं.

वाहन के प्रकार

वाहन की इकाई में VehicleType का एक ज़रूरी फ़ील्ड होता है. इसमें Category एनम होता है. इसे AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE या PEDESTRIAN के तौर पर दिखाया जा सकता है. वाहन का टाइप, SearchVehicles और ListVehicles में फ़िल्टर की शर्तों के तौर पर काम कर सकता है.

अगर कैटगरी को AUTO, TWO_WHEELER, BICYCLE या PEDESTRIAN पर सेट किया गया है, तो वाहनों के लिए सभी रूटिंग में इनसे जुड़े RouteTravelMode का इस्तेमाल होगा. अगर कैटगरी को TAXI या TRUCK पर सेट किया गया है, तो रूटिंग को AUTO मोड जैसा ही माना जाता है.

वाहन की विशेषताएं

वाहन की इकाई में VehicleAttribute का दोहराया गया फ़ील्ड है. फ़्लीट इंजन इन एट्रिब्यूट का इस्तेमाल नहीं करता. SearchVehicles एपीआई में एक फ़ील्ड शामिल होता है. यह ज़रूरी है कि मेल खाने वाले Vehicles में, बताई गई वैल्यू के लिए सेट किए गए सभी एट्रिब्यूट शामिल हों.

ध्यान दें कि एट्रिब्यूट फ़ील्ड के साथ-साथ Vehicle मैसेज में काम करने वाले दूसरे फ़ील्ड भी होते हैं, जैसे कि vehicle_type और supported_trip_types.

वाहन के बचे हुए वेपॉइंट

वाहन की इकाई में TripWaypoint (RPC | REST) का दोहराया गया फ़ील्ड होता है, जिसे waypoints(RPC | REST) कहा जाता है. इस फ़ील्ड में यात्राओं के बाकी वेपॉइंट शामिल होते हैं, जिस क्रम में वाहन उन तक पहुंचता है. फ़्लीट इंजन, इस फ़ील्ड को वाहन के लिए असाइन की गई यात्राओं के तौर पर इस्तेमाल करता है. यह यात्रा के स्टेटस में बदलाव होने पर इसे अपडेट करता है. इन वेपॉइंट की पहचान TripId फ़ील्ड और WaypointType फ़ील्ड से की जा सकती है.

मिलान के लिए किसी वाहन की ज़रूरी शर्तें पूरी करना

आम तौर पर, यात्रा के अनुरोधों को वाहनों से मैच करने के लिए, राइडशेयर या डिलीवरी की सेवा देने वाली कंपनी ज़िम्मेदार होती है. यह सेवा, वाहन के एट्रिब्यूट का इस्तेमाल करके, किसी वाहन को बड़ी संख्या में खोज के नतीजों में शामिल कर सकती है. उदाहरण के लिए, सेवा देने वाली कंपनी, वाहन से मिलने वाले फ़ायदों या क्षमताओं के लेवल के हिसाब से एट्रिब्यूट के लिए एक सेट लागू कर सकती है. उदाहरण के लिए, तीन लेवल, बूलियन वैल्यू वाले एट्रिब्यूट का सेट हो सकते हैं: is_bronze_level, is_silver_level, और is_gold_level. एक वाहन, इन तीनों पर काम कर सकता है. जब फ़्लीट इंजन को किसी ऐसी यात्रा के लिए अनुरोध मिलता है जिसके लिए सिल्वर लेवल की क्षमता की ज़रूरत होती है, तो खोज में उस वाहन को शामिल किया जाता है. इस तरीके से एट्रिब्यूट का इस्तेमाल करने पर, ऐसे वाहन शामिल होते हैं जिन पर कई तरह की सुविधाएं दी जा सकती हैं.

वाहन के एट्रिब्यूट अपडेट करने के दो तरीके हैं. इनमें से एक, UpdateVehicle एपीआई है. इस एपीआई का इस्तेमाल करते समय, वाहन एट्रिब्यूट का पूरा सेट वैल्यू पर सेट हो जाता है. सिर्फ़ एक एट्रिब्यूट को अपडेट नहीं किया जा सकता. दूसरा तरीका UpdateVehicleAttributes एपीआई है. इस तरीके में, सिर्फ़ एट्रिब्यूट को अपडेट करने की ज़रूरत होती है. अनुरोध में शामिल किए गए एट्रिब्यूट की वैल्यू, नई वैल्यू पर सेट की जाएगी या जोड़ी जाएगी. हालांकि, जिन एट्रिब्यूट के बारे में जानकारी नहीं दी गई है उनमें कोई बदलाव नहीं किया जाएगा.

कैसे करें: वाहन बनाएं

फ़्लीट में शामिल हर वाहन को ट्रैक करने के लिए, Vehicle इकाई बनाना ज़रूरी है.

वाहन बनाने के लिए, CreateVehicleRequest के साथ CreateVehicle एंडपॉइंट का इस्तेमाल करें.

Vehicle का provider_id, Google Cloud प्रोजेक्ट का प्रोजेक्ट आईडी (जैसे, my-on-demand-project) होना चाहिए. इसमें ऐसे सेवा खाते शामिल होने चाहिए जिनका इस्तेमाल Fleet Engine को कॉल करने के लिए किया जाएगा. ध्यान दें कि एक ही राइडशेयर या डिलीवरी देने वाली कंपनी के लिए, कई सेवा खाते फ़्लीट इंजन को ऐक्सेस कर सकते हैं. हालांकि, फ़िलहाल Fleet Engine एक ही Vehicles को ऐक्सेस करने वाले कई Google Cloud प्रोजेक्ट के सेवा खातों के लिए काम नहीं करता.

Vehicle को OFFLINE या ONLINE स्थिति में बनाया जा सकता है. अगर ONLINE बनाया गया है, तो इसे SearchVehicles क्वेरी के जवाब में तुरंत दिख सकता है.

CreateVehicle कॉल में शुरुआती last_location शामिल किया जा सकता है. हालांकि, इस बात की अनुमति है कि ONLINE में last_location के बिना, Vehicle नहीं बनाया जाना चाहिए.

वाहन किस तरह का है, इसकी जानकारी देने के लिए वाहन के टाइप देखें.

एट्रिब्यूट फ़ील्ड की जानकारी के लिए, वाहन के एट्रिब्यूट देखें.

CreateVehicle से मिला मान, बनाई गई Vehicle इकाई है.

उदाहरण

शेल

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 के लॉग

CreateVehicle एंडपॉइंट पर कॉल मिलने पर, Fleet Engine API, Google Cloud प्लैटफ़ॉर्म लॉग के ज़रिए लॉग एंट्री लिखता है. लॉग एंट्री में, CreateVehicle अनुरोध में दी गई वैल्यू की जानकारी शामिल होती है. अगर कॉल पूरा हो जाता है, तो इसमें लौटाए गए Vehicle की जानकारी भी शामिल होगी.

शेल

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 के ज़रिए एक सूचना पब्लिश करता है. ये सूचनाएं पाने के लिए, कृपया यहां दिए गए निर्देशों का पालन करें.

कैसे करें: वाहन की जगह की जानकारी अपडेट करना

अगर वाहन की जगह की जानकारी अपडेट करने के लिए ड्राइवर SDK टूल का इस्तेमाल नहीं किया जा रहा है, तो वाहन की जगह की जानकारी के साथ Fleet Engine को सीधे कॉल किया जा सकता है. किसी भी चालू वाहन के लिए, Fleet Engine हर मिनट में कम से कम एक बार और हर पांच सेकंड में एक बार जगह की जानकारी अपडेट करना चाहता है. इन अपडेट के लिए, सिर्फ़ Fleet Engine ड्राइवर SDK टूल के उपयोगकर्ता के खास अधिकारों की ज़रूरत होती है.

उदाहरण

शेल

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 के अलावा अन्य एट्रिब्यूट की वैल्यू अपडेट करने के लिए, फ़्लीट इंजन के सुपर यूज़र के खास अधिकार ज़रूरी हैं.

किन फ़ील्ड को अपडेट करना है, यह बताने के लिए UpdateVehicleRequest में एक update_mask शामिल होता है. फ़ील्ड मास्क के काम करने का तरीका प्रोटोबफ़ दस्तावेज़ में बताया गया है.

जैसा कि वाहन के एट्रिब्यूट में बताया गया है, attributes फ़ील्ड को अपडेट करने के लिए, सभी एट्रिब्यूट को सेव रखना ज़रूरी है. UpdateVehicle कॉल में, सिर्फ़ एक की-वैल्यू पेयर की वैल्यू अपडेट नहीं की जा सकती. खास एट्रिब्यूट की वैल्यू अपडेट करने के लिए, UpdateVehicleAttributes एपीआई का इस्तेमाल किया जा सकता है.

उदाहरण

इस उदाहरण में, back_to_back चालू होता है.

शेल

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 के लॉग

UpdateVehicle एंडपॉइंट पर कॉल मिलने पर, Fleet Engine API, Google Cloud प्लैटफ़ॉर्म लॉग के ज़रिए लॉग एंट्री लिखता है. लॉग एंट्री में, UpdateVehicle अनुरोध में दी गई वैल्यू की जानकारी शामिल होती है. अगर कॉल पूरा हो जाता है, तो इसमें लौटाए गए Vehicle की जानकारी भी शामिल होगी.

शेल

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 के ज़रिए एक सूचना पब्लिश करता है. ये सूचनाएं पाने के लिए, कृपया यहां दिए गए निर्देशों का पालन करें.

कैसे करें: वाहन खोजें

यह फ़्लीट इंजन, गाड़ियों की खोज करने की सुविधा देता है. SearchVehicles एपीआई की मदद से, आपको आस-पास मौजूद ऐसे ड्राइवर ढूंढने में मदद मिलती है जो राइड की बुकिंग या डिलीवरी का अनुरोध करने जैसे काम के लिए सबसे सही हों. SearchVehicles एपीआई, आपके वाहन के एट्रिब्यूट के साथ टास्क एट्रिब्यूट को मैच करने वाले ड्राइवर की रैंक की सूची दिखाता है. ज़्यादा जानकारी के लिए, आस-पास मौजूद ड्राइवर ढूंढना देखें.

उदाहरण

उपलब्ध वाहनों की खोज करते समय, Fleet Engine ऐसी गाड़ियों को डिफ़ॉल्ट रूप से शामिल नहीं करता जो चालू यात्राओं पर होती हैं. राइडशेयर या डिलीवरी की सेवा देने वाली कंपनी की सेवाओं को, खोज के अनुरोधों में उन्हें साफ़ तौर पर शामिल करना चाहिए. यहां दिए गए उदाहरण में बताया गया है कि उन वाहनों की खोज में, ग्रैंड इंडोनेशिया ईस्ट मॉल से बलाई सिडांग जकार्ता कन्वेंशन सेंटर की यात्रा से मेल खाने वाले वाहन कैसे शामिल करें.

शेल

सबसे पहले, पिछले चरणों में बनाए गए वाहन की जगह की जानकारी अपडेट करें, ताकि वह ज़रूरी शर्तों को पूरा कर सके. असल में, यह काम Android या iOS डिवाइस पर चलने वाले ड्राइवर SDK टूल के ज़रिए किया जा सकता है.

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 क्लॉज़ के तौर पर काम करती है, जैसे कि SearchVehiclesRequest में minimum_capacity या vehicle_types.

कैसे करें: वाहनों की सूची बनाना

SearchVehicles को, तय क्रम में बहुत कम गाड़ियों को तुरंत खोजने के लिए ऑप्टिमाइज़ किया गया है. इसका इस्तेमाल मुख्य रूप से, आस-पास मौजूद ऐसे ड्राइवर खोजने के लिए किया जाता है जो किसी काम के लिए सबसे सही हों. हालांकि, कभी-कभी आप कुछ शर्तों को पूरा करने वाली सभी गाड़ियों को ढूंढना चाहते हैं, भले ही नतीजों को पेज करना ज़रूरी हो. ListVehicles को इस तरह के इस्तेमाल के लिए डिज़ाइन किया गया है.

ListVehicles एपीआई की मदद से, उन सभी वाहनों को ढूंढा जा सकता है जो अनुरोध के कुछ खास विकल्पों को पूरा करते हैं. ListVehicles एपीआई, ऐसे प्रोजेक्ट में वाहनों की पेज नंबर वाली सूची दिखाता है जो कुछ ज़रूरी शर्तों को पूरा करता है.

वाहन के एट्रिब्यूट फ़िल्टर करने के लिए, कृपया वाहन के लिए फ़िल्टर करने से जुड़ी क्वेरी देखें.

उदाहरण

इस उदाहरण में, filter स्ट्रिंग का इस्तेमाल करके vehicle_type और एट्रिब्यूट को फ़िल्टर किया गया है.

शेल

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 और लाइफ़साइकल, Vehicle API और लाइफ़साइकल जैसे होते हैं. राइडशेयर की सुविधा देने वाली कंपनी की ज़िम्मेदारी है कि वह Fleet Engine इंटरफ़ेस का इस्तेमाल करके, यात्रा बनाए. Fleet Engine, आरपीसी सेवा, TripService, और REST के संसाधन provider.trips, दोनों उपलब्ध कराता है. ये इंटरफ़ेस यात्रा की इकाई बनाने, जानकारी के अनुरोध, खोज की सुविधा, और अपडेट की क्षमता को चालू करते हैं.

Trip में एक स्टेटस फ़ील्ड होता है, जो लाइफ़साइकल के ज़रिए उसकी प्रोग्रेस को ट्रैक करता है. इसके वैल्यू, NEW से COMPLETE के साथ-साथ CANCELED और UNKNOWN_TRIP_STATUS में बदल जाती हैं . आरपीसी के लिए trip_status या REST के लिए TripStatus देखें.

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

आपकी सेवा इनमें से किसी भी स्थिति से, CANCELED के लिए यात्रा को अपडेट कर सकती है. जब आपकी सेवा के लिए यात्रा शुरू की जाती है, तब इंजन, स्थिति को NEW के तौर पर सेट करता है. vehicle_id ज़रूरी नहीं है. वाहनों की तरह, ये सेवाएं सात दिन बाद बिना किसी अपडेट के अपने-आप यात्राओं को मिटा देती हैं. अगर आपकी सेवा पहले से मौजूद किसी आईडी के साथ यात्रा बनाने की कोशिश करती है, तो एक गड़बड़ी दिखती है. अगर यात्रा की स्थिति COMPLETE या CANCELED के अलावा किसी और स्थिति में है, तो उसे ‘चालू है’ माना जाता है. यह अंतर, वाहन इकाई और SearchTripsRequest के active_trips फ़ील्ड में ज़रूरी है.

आपकी सेवा, यात्रा के लिए असाइन किए गए vehicle_id को सिर्फ़ तब बदल सकती है, जब यात्रा चालू हो. उदाहरण के लिए, आप ऐसा तब करेंगे जब कोई ड्राइवर रास्ते में यात्रा रद्द करता है और यात्रा किसी दूसरे वाहन पर असाइन हो जाती है.

बैक-टू-ट्रिप सहायता लागू करते समय, स्थिति अहम होती है. इस सहायता की मदद से, सेवा देने वाली कंपनी, चालू यात्रा पर वाहन के लिए नई यात्रा असाइन कर सकती है. बैक-टू-बैक यात्रा के लिए कोड वही है जो एक यात्रा के लिए बनाया गया है. साथ ही, इसमें एक ही वाहन आईडी का इस्तेमाल किया जाता है. फ़्लीट इंजन, नई यात्रा की शुरुआत की जगह और मंज़िल की जानकारी, वाहन के वेपॉइंट में जोड़ता है. एक-एक करके जाने वाली यात्राओं के बारे में ज़्यादा जानकारी के लिए, मल्टी-वेपॉइंट यात्राएं बनाएं देखें.

यात्रा के बचे हुए वेपॉइंट

यात्रा की इकाई में TripWaypoint (RPC | REST) का दोहराया गया फ़ील्ड होता है, जिसे remainingWaypoints(RPC | REST) कहते हैं. इस फ़ील्ड में वे सभी वेपॉइंट शामिल हैं जिन पर इस यात्रा के आखिरी ड्रॉप पॉइंट से पहले, वाहन को क्रम से चलना होगा. इसका हिसाब, वाहन के बाकी वेपॉइंट से लगाया जाता है. बैक-टू-बैक और कारपूल के इस्तेमाल के उदाहरणों में, इस सूची में उन दूसरी यात्राओं के वेपॉइंट शामिल होते हैं जिन्हें इस यात्रा से पहले पार किया जाएगा. हालांकि, इसमें वेपॉइंट शामिल नहीं होंगे. सूची में वेपॉइंट को उसके TripId और WaypointType से पहचाना जा सकता है.

यात्रा की स्थिति और वाहन के बचे हुए वेपॉइंट के बीच का संबंध

जब फ़्लीट इंजन को यात्रा की स्थिति बदलने का अनुरोध मिलता है, तब वाहन के बचे हुए वेपॉइंट (RPC | REST) को अपडेट कर दिया जाएगा. tripStatus(RPC | REST) को अन्य स्टेटस से ENROUTE_TO_XXX करने पर, पिछले वेपॉइंट को वाहन के बाकी वेपॉइंट की सूची से हटा दिया जाएगा. इसका मतलब है कि जब यात्रा की स्थिति को ENROUTE_TO_PICKUP से ARRIVED_AT_PICKUP में बदला जाता है, तब भी यात्रा का पिक अप पॉइंट, वाहन की बाकी वेपॉइंट सूची में रहेगा. हालांकि, यात्रा की स्थिति ENROUTE_TO_INTERTE_DESTINATION या ENROUTE_TO_DROPOFF में करने पर, इसका पिक अप पॉइंट वाहन के रास्ते से हटा दिया जाएगा.

ARRIVED_AT_INTERMEDIATE_DESTINATION और ENROUTE_TO_INTERMDEDIATE_DESTINATION के लिए भी ऐसा ही होता है. ARRIVED_AT_INTERMEDIATE_DESTINATION पर, मौजूदा इंटरमीडिएट डेस्टिनेशन को वाहन की बची हुई वेपॉइंट की सूची से तब तक नहीं हटाया जाएगा, जब तक कि वाहन यह रिपोर्ट न करे कि वह रास्ते में है.

यात्रा की स्थिति को COMPLETED में बदलने पर, इस यात्रा से जुड़ा कोई भी वेपॉइंट, वाहन की बाकी वेपॉइंट की सूची में नहीं दिखेगा.

कैसे करें: यात्रा बनाएं

हर यात्रा अनुरोध को ट्रैक करने और उसे फ़्लीट में मौजूद वाहनों से मैच कराने के लिए, Trip इकाई बनाई जानी चाहिए. यात्रा बनाने के लिए, CreateTripRequest के साथ CreateTrip एंडपॉइंट का इस्तेमाल करें.

यात्रा बनाने के लिए इन एट्रिब्यूट की ज़रूरत है:

  • parent - इस स्ट्रिंग में, कंपनी का आईडी शामिल होता है. यह आईडी Google Cloud प्रोजेक्ट के बनाए जाने के दौरान बनाया जाता है.
  • trip_id - राइडशेयर की सुविधा देने वाली कंपनी की ओर से बनाई गई स्ट्रिंग.
  • trip - यात्रा के बारे में जानकारी देने वाला बेसिक मेटाडेटा वाला कंटेनर.
    • trip_type - Enum से पता चलता है कि यात्रा के अन्य यात्री एक ही वाहन (SHARED) में या सिर्फ़ एक पक्ष (EXCLUSIVE) में, अलग-अलग ऑरिजिन और डेस्टिनेशन से आ सकते हैं.
    • pickup_point - TerminalLocation, यात्रा की शुरुआत की जगह को दिखाता है. RPC रेफ़रंस या REST रेफ़रंस देखें

यात्रा बनाते समय, number_of_passengers, dropoff_point, और vehicle_id की जानकारी दी जा सकती है. हालांकि, इन फ़ील्ड की ज़रूरत नहीं है, लेकिन अगर आप फ़ील्ड उपलब्ध कराते हैं, तो उन्हें सेव रखा जाता है. अन्य सभी यात्रा फ़ील्ड को अनदेखा कर दिया जाता है. उदाहरण के लिए, सभी यात्राओं की शुरुआत NEW के trip_status से होती है, भले ही आपने यात्रा बनाने के अनुरोध में CANCELED के trip_status दिए हों.

उदाहरण

नीचे दिया गया उदाहरण, ग्रैंड इंडोनेशिया ईस्ट मॉल की यात्रा बनाता है. यह यात्रा दो यात्रियों के लिए है और यह खास है. Trip का provider_id और प्रोजेक्ट आईडी एक ही होना चाहिए. उदाहरण में, राइडशेयर की सुविधा देने वाली कंपनी ने Google Cloud प्रोजेक्ट, project-id बनाया. इस प्रोजेक्ट में ऐसे सेवा खाते होने चाहिए जिनका इस्तेमाल, फ़्लीट इंजन को कॉल करने के लिए किया जाता है. यात्रा की स्थिति NEW है.

बाद में, यात्रा को वाहन के साथ मैच करने के बाद, सेवा UpdateTrip को कॉल कर सकती है. साथ ही, वाहन को यात्रा असाइन किए जाने पर vehicle_id को बदल सकती है.

शेल

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 प्लैटफ़ॉर्म के लॉग

CreateTrip एंडपॉइंट पर कॉल मिलने पर, Fleet Engine API, Google Cloud प्लैटफ़ॉर्म लॉग का इस्तेमाल करके लॉग एंट्री लिखता है. लॉग एंट्री में, CreateTrip अनुरोध में दी गई वैल्यू की जानकारी शामिल होती है. अगर कॉल पूरा हो जाता है, तो इसमें लौटाए गए Trip की जानकारी भी शामिल होगी.

कैसे करें: यात्रा को अपडेट करना

यात्रा की इकाई में ऐसे फ़ील्ड होते हैं जिनकी मदद से सेवा के आधार पर ट्रैकिंग की जा सकती है. साथ ही, ड्राइवर SDK टूल और उपभोक्ता SDK से यात्रा की प्रोग्रेस की रिपोर्ट भी दी जा सकती है. प्रॉपर्टी अपडेट करने के लिए, UpdateTripRequest मैसेज का इस्तेमाल करें. इससे यात्रा के फ़ील्ड, अनुरोध की गई field_mask के मुताबिक अपडेट हो जाते हैं. UpdateTripRequest पर जाएं.

इन एट्रिब्यूट को अपडेट करने की ज़िम्मेदारी राइडशेयर की सुविधा देने वाली कंपनी की होती है:

  • यात्रा की स्थिति.
  • वाहन का आईडी. टिकट बनाते समय या वाहन का मिलान यात्रा से करने के बाद.
  • पिकअप, ड्रॉप-ऑफ़ या वेपॉइंट में बदलाव.

ड्राइवर SDK टूल या कंज़्यूमर SDK टूल से, जर्नी शेयरिंग की सुविधा का इस्तेमाल करते समय, Fleet Engine इन फ़ील्ड को अपने-आप अपडेट करता है:

  • रास्ते
  • ईटीए
  • शेष दूरी
  • वाहन की जगह की जानकारी
  • बाकी वेपॉइंट

Tripआरपीसी में या REST में मौजूद Resource.Trip देखें.

यात्रा से जुड़े अपडेट के लिए Google Cloud Platform के लॉग

UpdateTrip एंडपॉइंट पर कॉल मिलने पर, Fleet Engine API, Google Cloud प्लैटफ़ॉर्म लॉग का इस्तेमाल करके लॉग एंट्री लिखता है. लॉग एंट्री में, UpdateTrip अनुरोध में दी गई वैल्यू की जानकारी शामिल होती है. अगर कॉल पूरा हो जाता है, तो इसमें लौटाए गए Trip के बारे में भी जानकारी शामिल होगी.

कैसे करें: यात्राओं के लिए खोजें

Fleet Engine, यात्राओं के बारे में जानकारी खोजने की सुविधा देता है. जैसा कि पहले बताया गया है, यात्रा सात दिनों के बाद अपने-आप मिट जाती है, इसलिए SearchTrips सभी यात्राओं का पूरा इतिहास नहीं दिखाता.

SearchTrips एक सुविधाजनक एपीआई है, लेकिन नीचे दी गई सूची में, इस्तेमाल के दो उदाहरणों पर ध्यान दिया गया है.

  • किसी वाहन की चालू यात्राओं की जानकारी तय करना -- सेवा देने वाली कंपनी, किसी वाहन की मौजूदा यात्राओं की जानकारी का पता लगा सकती है. SearchTripsRequest में, vehicle_id को वाहन पर सेट किया गया है और active_trips_only true पर सेट होना चाहिए.

  • सेवा देने वाली कंपनी और फ़्लीट इंजन की स्थिति का मिलान करना -- सेवा देने वाली कंपनी, SearchTrips का इस्तेमाल कर सकती है, ताकि यह पक्का किया जा सके कि उसकी यात्रा की स्थिति और फ़्लीट इंजन की स्थिति एक जैसी हो. यह TripStatus के लिए खास तौर पर ज़रूरी है. अगर किसी वाहन को असाइन की गई यात्रा की स्थिति ठीक से COMPLETE या CANCELED पर सेट नहीं की गई है, तो वाहन को SearchVehicles में शामिल नहीं किया जाता है.

इस तरह SearchTrips का इस्तेमाल करने के लिए, vehicle_id को खाली छोड़ें, active_trips_only को true पर सेट करें, और minimum_staleness को ऐसी अवधि पर सेट करें जो ज़्यादातर यात्रा की अवधि से ज़्यादा हो. उदाहरण के लिए, एक घंटे का समय दिया जा सकता है. नतीजों में ऐसी यात्राएं शामिल हैं जो न तो पूरी हैं और न ही रद्द की गई हैं. साथ ही, जिन्हें एक घंटे से ज़्यादा समय से अपडेट नहीं किया गया है. सेवा देने वाली कंपनी को इन यात्राओं की जांच करनी चाहिए, ताकि यह पक्का किया जा सके कि फ़्लीट इंजन में इनकी स्थिति सही तरीके से अपडेट की गई है.

समस्या हल करना

DEADLINE_EXCEEDED गड़बड़ी के मामले में, फ़्लीट इंजन की स्थिति के बारे में जानकारी नहीं है. सेवा देने वाली कंपनी को CreateTrip को फिर से कॉल करना चाहिए, जो या तो 201 (CREATED) या 409 (कॉन्फ़्लिक्ट) दिखाता है. बाद वाले मामले में, पिछला अनुरोध DEADLINE_EXCEEDED से पहले पूरा हो गया था. यात्रा से जुड़ी गड़बड़ियों को मैनेज करने के बारे में ज़्यादा जानकारी के लिए, Consumer API गाइड देखें: Android या iOS.

कारपूल राइड से जुड़ी सहायता

TripType.SHARED की सुविधा वाले वाहन के लिए, SHARED की एक से ज़्यादा यात्राएं असाइन की जा सकती हैं. शेयर की गई यात्रा (CreateTrip या UpdateTrip के अनुरोध में) के लिए vehicle_id असाइन करते समय, Trip.vehicle_waypoints से शेयर की जाने वाली इस राइड में, वाहन को असाइन की गई सभी यात्राओं के लिए उन सभी यात्राओं के लिए पॉइंट का क्रम तय करना होगा जो रास्ते में नहीं हैं. आरपीसी के लिए vehicle_waypoints या REST के लिए vehicleWaypoints देखें.

एक से ज़्यादा डेस्टिनेशन का इस्तेमाल किया जा सकता है

किसी मध्यवर्ती गंतव्य की पहचान करना

यात्रा के फ़ील्ड intermediateDestinations और फ़ील्ड intermediateDestinationIndex (RPC | REST) को डेस्टिनेशन की जानकारी देने के लिए इस्तेमाल किया जाता है.

इंटरमीडिएट डेस्टिनेशन अपडेट करें

बीच के डेस्टिनेशन को UpdateTrip की मदद से अपडेट किया जा सकता है. बीच के लेवल पर मिलने वाले डेस्टिनेशन की जानकारी अपडेट करते समय, आपको इंटरमीडिएट डेस्टिनेशन की पूरी सूची देनी होगी. इसमें उन डेस्टिनेशन की पूरी सूची भी शामिल होनी चाहिए जिन पर विज़िट किया जा चुका है. इसमें, सिर्फ़ ऐसे डेस्टिनेशन की सूची भी शामिल नहीं करनी होगी जिन्हें हाल ही में जोड़ा गया है या जिनमें बदलाव किया गया है. जब intermediateDestinationIndex, जोड़े गए नए/बदलाव किए गए इंटरमीडिएट डेस्टिनेशन की स्थिति के बाद, इंडेक्स पर ले जाता है, तो नए/अपडेट किए गए इंटरमीडिएट डेस्टिनेशन को, वाहन के waypoints या यात्रा के remainingWaypoints में नहीं जोड़ा जाएगा. इसकी वजह यह है कि intermediateDestinationIndex से पहले के किसी भी इंटरमीडिएट डेस्टिनेशन को पहले ही विज़िट किया गया माना जाता है.

यात्रा की स्थिति में बदलाव

Fleet Engine को यात्रा की स्थिति अपडेट करने का अनुरोध भेजे जाने के लिए, (RPC | REST) फ़ील्ड में intermediateDestinationsVersion फ़ील्ड ज़रूरी होता है. इससे यह पता चलता है कि इंटरमीडिएट डेस्टिनेशन पास हो चुका है. टारगेट किए गए इंटरमीडिएट डेस्टिनेशन को 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 प्रोजेक्ट के बनाए गए विषय से जुड़ी सूचनाएं पब्लिश करता है. आपके Google Cloud प्रोजेक्ट में, Fleet Engine के लिए Pub/Sub डिफ़ॉल्ट रूप से चालू नहीं होता है. कृपया सहायता अनुरोध दर्ज करें या Pub/Sub की सुविधा चालू करने के लिए, अपने कस्टमर इंजीनियर से संपर्क करें.

अपने Cloud प्रोजेक्ट पर कोई विषय बनाने के लिए, इन निर्देशों का पालन करें. विषय का आईडी, 'fleet_engine_Notifications' पर होना चाहिए.

इस विषय को उसी Cloud प्रोजेक्ट में बनाया जाना चाहिए जिसमें Fleet Engine API को कॉल किया जा रहा है.

विषय बनाने के बाद, आपको Fleet Engine API को इस विषय पर कॉन्टेंट पब्लिश करने की अनुमति देनी होगी. ऐसा करने के लिए, अभी-अभी बनाए गए विषय पर क्लिक करें और नई अनुमति जोड़ें. अनुमति एडिटर को खोलने के लिए, हो सकता है कि आपको जानकारी वाला पैनल दिखाएं पर क्लिक करना पड़े. मुख्य भूमिका geo-fleet-engine@system.gserviceaccount.com होनी चाहिए और भूमिका Pub/Sub publisher होनी चाहिए.

सूचनाएं पाने की सदस्यता लेने के लिए अपने Cloud प्रोजेक्ट को सेटअप करने के लिए, इन निर्देशों का पालन करें

Fleet Engine API हर सूचना को, दो अलग-अलग डेटा फ़ॉर्मैट 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"
    }
  }
}