استخدام الرموز المميزة للجلسة

تعمل الرموز المميزة للجلسة على تجميع مرحلتي الاستعلام والاختيار من عملية الإكمال التلقائي للمستخدم للبحث في جلسة منفصلة لأغراض الفوترة. توضح الأمثلة التالية كيفية استخدام الرموز المميزة للجلسة في استدعاءات الإكمال التلقائي (جديد) وتفاصيل المكان (جديد).

إنشاء رمز مميز للجلسة

ويتحمّل المستخدمون مسؤولية إنشاء رموز مميّزة فريدة للجلسة لكل جلسة. تنصح Google باستخدام الإصدار 4 من المعرّفات الفريدة العالمية (UUID).

تقديم طلب إكمال تلقائي (جديد)

طلب الإكمال التلقائي (الجديد) هو طلب HTTP POST. للمزيد من المعلومات حول مَعلمات نص الطلب، اطّلِع على طلبات وضع الإكمال التلقائي (جديد).

تعرض سلسلة الطلبات التالية مستخدمًا يبحث عن مطعم بيتزا في القاهرة. عندما يبدأ المستخدم في كتابة استعلام، يتم استدعاء الإكمال التلقائي (جديد) لكل ضغطة مفتاح. يتم تمرير الرمز المميز للجلسة الذي تم إنشاؤه كمعلمة في كل استدعاء.

الطلب الأول والردّ

الطلب رقم 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"
        ]
      }
    },
  /.../
  ]
}

إنهاء الجلسة

قم بإنهاء جلسة عن طريق تقديم طلب للتحقق من صحة تفاصيل المكان (جديد) أو العنوان، وتمرير الرمز المميز نفسه للجلسة الذي استخدمته في طلبات الإكمال التلقائي (الجديد).

طلب إنشاء تفاصيل مكان (جديد)

طلب تفاصيل المكان (جديد) هو طلب 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 في استجابة الإكمال التلقائي (جديد)، وعنوان sessionToken المستخدم في طلبات الإكمال التلقائي (الجديد) السابقة.

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

تجاهل جلسة

يتم إنهاء الجلسة إذا تركها المستخدم. على سبيل المثال، إذا بدأ المستخدم البحث عن مطعم بيتزا ولكنه لم يحدد مكانًا (يؤدي إلى تشغيل استدعاء تفاصيل المكان (جديد)) أو يتحقق من صحة العنوان (تشغيل استدعاء التحقق من العنوان)، تنتهي الجلسة وتنتهي صلاحية الرمز المميز للجلسة.