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

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

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

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

ملاحظة: يمكن أن تتداخل الرموز المميّزة للجلسة في مشاريع Google Cloud Console، ولكن يجب أن تكون فريدة لكل مشروع. على سبيل المثال، يمكن لتطبيق يستخدم المشروع "أ" وتطبيق "المشروع ب" استخدام الرمز المميز للجلسة نفسه، لكن لا يمكن لعدة تطبيقات تستخدم المشروع "أ" استخدام الرمز المميز للجلسة نفسه.

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

طلب الإكمال التلقائي (الجديد) هو طلب 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"
        ]
      }
    },
  /.../
  ]
}

ملاحظة: يمكنك استخدام مَعلمة inputOffset الاختيارية لتحديد موضع المؤشر في حقل الإدخال.

إنهاء الجلسة

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

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

طلب تفاصيل المكان (جديد) هو طلب 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"
    }

مغادرة جلسة

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