שימוש באסימוני סשן
אסימוני סשן מקבצים את שלבי השאילתה והבחירה בחיפוש של המשתמש להשלמה אוטומטית לסשן נפרד למטרות חיוב. בדוגמאות הבאות מוסבר איך להשתמש באסימוני סשן בקריאות להשלמה אוטומטית (חדש) ולפרטי מקום (חדש).
יצירת טוקן סשן
המשתמשים אחראים ליצור אסימוני סשן ייחודיים לכל סשן. Google ממליצה להשתמש במזהים ייחודיים אוניברסליים (UUID) בגרסה 4.
שליחת בקשה להשלמה אוטומטית (חדשה)
בקשה מסוג Autocomplete (חדש) היא בקשת HTTP POST. מידע נוסף על פרמטרים של גוף הבקשה זמין במאמר בנושא בקשות Place Autocomplete (חדש).
סדרת הבקשות הבאה מראה משתמש שמחפש פיצרייה בסן פרנסיסקו. כשהמשתמש מתחיל להקליד שאילתות, המערכת מפעילה את ההשלמה האוטומטית (חדשה) לכל הקשה על מקש. אסימון הסשן שנוצר מועבר כפרמטר בכל קריאה.
הבקשה והתגובה הראשונות
בקשה 1
curl -X POST -d '{ "input": "p", "sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' -H 'Content-Type: application/json' -H "X-Goog-Api-Key: YOUR_API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
תגובה 1
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJHSGzi_yAhYARnrPmDWAx9ro", "placeId": "ChIJHSGzi_yAhYARnrPmDWAx9ro", "text": { "text": "PIER 39, The Embarcadero, San Francisco, CA, USA", "matches": [ { "endOffset": 1 } ] }, "structuredFormat": { "mainText": { "text": "PIER 39", "matches": [ { "endOffset": 1 } ] }, "secondaryText": { "text": "The Embarcadero, San Francisco, CA, USA" } }, "types": [ "historical_landmark", "shopping_mall", "point_of_interest", "establishment", "marina", "tourist_attraction" ] } }, ] / ... / }
בקשה ותגובה שנייה
בקשה 2
curl -X POST -d '{ "input": "pi", "sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' -H 'Content-Type: application/json' -H "X-Goog-Api-Key: YOUR_API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
תגובה 2
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJHSGzi_yAhYARnrPmDWAx9ro", "placeId": "ChIJHSGzi_yAhYARnrPmDWAx9ro", "text": { "text": "PIER 39, The Embarcadero, San Francisco, CA, USA", "matches": [ { "endOffset": 2 } ] }, "structuredFormat": { "mainText": { "text": "PIER 39", "matches": [ { "endOffset": 2 } ] }, "secondaryText": { "text": "The Embarcadero, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "shopping_mall", "marina", "historical_landmark", "tourist_attraction" ] } }, /.../ ] }
בקשה ותגובה שלישית
בקשה 3
curl -X POST -d '{ "input": "piz", "sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' -H 'Content-Type: application/json' -H "X-Goog-Api-Key: YOUR_API_KEY" https://places.googleapis.com/v1/places:autocomplete
תגובה 3
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ_QJSSfGAhYARQVFJBNKy3HE", "placeId": "ChIJ_QJSSfGAhYARQVFJBNKy3HE", "text": { "text": "Pizza By The Slice, Grant Avenue, San Francisco, CA, USA", "matches": [ { "endOffset": 3 } ] }, "structuredFormat": { "mainText": { "text": "Pizza By The Slice", "matches": [ { "endOffset": 3 } ] }, "secondaryText": { "text": "Grant Avenue, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "food", "pizza_restaurant", "restaurant" ] } }, /.../ ] }
סיום הסשן
כדי לסיים סשן, שולחים בקשה ל-Place Details (New) או ל-Address Validation ומעבירים את אותו אסימון סשן שבו השתמשתם בבקשות Autocomplete (New).
שליחת בקשה חדשה לגבי פרטי מקום
בקשה מסוג פרטי מקום (חדש) היא בקשת HTTP GET. מידע נוסף על פרמטרים של גוף הבקשה זמין בבקשות פרטי מקום (חדש).
הבקשה הבאה של פרטי מקום (חדש) כוללת את ה-id
של המקום שנבחר ואת ה-sessionToken
ששימש בקריאות קודמות של השלמה אוטומטית (חדש).
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: YOUR_API_KEY" \ -H "X-Goog-FieldMask: id,displayName,accessibilityOptions,businessStatus" \ https://places.googleapis.com/v1/places/ChIJ_QJSSfGAhYARQVFJBNKy3HE?sessionToken=3519edfe-0f75-4a30-bfe4-7cbd89340b2c
כשמשתמשים במקום id
של ChIJ_QJSSfGAhYARQVFJBNKy3HE
, הקריאה יוצרת את התגובה הבאה בפורמט JSON:
{ "id": "ChIJ_QJSSfGAhYARQVFJBNKy3HE", "businessStatus": "OPERATIONAL", "displayName": { "text": "Pizza By The Slice", "languageCode": "en" }, "accessibilityOptions": { "wheelchairAccessibleParking": false, "wheelchairAccessibleEntrance": true } }
שליחת בקשה לאימות כתובת
בקשת אימות כתובת היא בקשת HTTP POST. למידע נוסף על הפרמטרים של גוף הבקשה, ראו שליחת בקשה לאימות כתובת.
הבקשה הבאה לאימות כתובת כוללת את הכתובת של המקום שנבחר, שנמצאת בשדהtext
בתשובה של Autocomplete (חדש), ואת הערך של sessionToken
ששימש בקריאות קודמות של Autocomplete (חדש).
curl -X POST -d '{ "sessionToken": "3519edfe-0f75-4a30-bfe4-7cbd89340b2c", "address": { "addressLines": "Pizza By The Slice, Grant Avenue, San Francisco, CA, USA" } }' \ -H 'Content-Type: application/json' \ "https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"
הקריאה יוצרת את תגובת ה-JSON הבאה:
{ "result": { "verdict": { "inputGranularity": "PREMISE", "validationGranularity": "PREMISE", "geocodeGranularity": "PREMISE", "hasInferredComponents": true }, "address": { "formattedAddress": "Pizza By The Slice, Grant Avenue, San Francisco, CA 94133, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94133", "administrativeArea": "CA", "locality": "San Francisco", "addressLines": [ "Pizza By The Slice", "Grant Ave" ] }, "addressComponents": [ { "componentName": { "text": "Pizza By The Slice", "languageCode": "en" }, "componentType": "point_of_interest", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "Grant Avenue", "languageCode": "en" }, "componentType": "route", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "San Francisco", "languageCode": "en" }, "componentType": "locality", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "CA", "languageCode": "en" }, "componentType": "administrative_area_level_1", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "USA", "languageCode": "en" }, "componentType": "country", "confirmationLevel": "CONFIRMED" }, { "componentName": { "text": "94133" }, "componentType": "postal_code", "confirmationLevel": "CONFIRMED", "inferred": true } ], "missingComponentTypes": [ "street_number" ] }, "geocode": { "location": { "latitude": 37.800504, "longitude": -122.4074794 }, "plusCode": { "globalCode": "849VRH2V+62" }, "bounds": { "low": { "latitude": 37.800504, "longitude": -122.4074794 }, "high": { "latitude": 37.800504, "longitude": -122.4074794 } }, "featureSizeMeters": 10, "placeId": "ChIJ_QJSSfGAhYARQVFJBNKy3HE", "placeTypes": [ "food", "restaurant", "point_of_interest", "establishment" ] }, "uspsData": { "standardizedAddress": { "firstAddressLine": "PIZZA BY THE SLICE", "secondAddressLine": "GRANT AVE", "cityStateZipAddressLine": "SAN FRANCISCO", "city": "SAN FRANCISCO", "state": "CA", "zipCode": "94133" }, "dpvFootnote": "A1M1", "postOfficeCity": "SAN FRANCISCO", "postOfficeState": "CA" } }, "responseId": "4b669675-2c3b-463a-ae20-400248cf6ac9" }
יציאה מפעילות
סשן מסתיים אם המשתמש נטש אותו. לדוגמה, אם משתמש מתחיל לחפש פיצרייה אבל לא בוחר מקום (מפעיל קריאה ל-Place Details (New)) או לא מאמת את הכתובת (מפעיל קריאה ל-Address Validation), הסשן מסתיים ותוקף אסימון הסשן פג.