Package google.type

الفهرس

• Date (رسالة)
• DayOfWeek (تعداد)
• Interval (رسالة)
• PhoneNumber (رسالة)
• PhoneNumber.ShortCode (رسالة)
• PostalAddress (رسالة)
• TimeOfDay (رسالة)
• TimeZone (رسالة)

التاريخ

يمثّل تاريخًا تقويميًا كاملاً أو جزئيًا، مثل تاريخ ميلاد. تم تحديد وقت اليوم والمنطقة الزمنية في مكان آخر أو أنّهما غير مهمّين. التاريخ نسبي إلى التقويم الغريغوري. يمكن أن يشير ذلك إلى أحد الخيارات التالية:

• تاريخ كامل، بقيم غير صفرية للسنة والشهر واليوم
• الشهر واليوم، مع سنة صفرية (مثلاً، ذكرى سنوية)
• سنة بمفردها، مع صفر شهر وصفر يوم
• سنة وشهر، مع يوم صفري (على سبيل المثال، تاريخ انتهاء صلاحية بطاقة الائتمان)

الأنواع ذات الصلة:

• google.type.TimeOfDay
• google.type.DateTime
• google.protobuf.Timestamp

الحقول
year	int32 السنة التي حدث فيها التاريخ. يجب أن تكون من 1 إلى 9999، أو 0 لتحديد تاريخ بدون عام.
month	int32 الشهر من السنة يجب أن يكون من 1 إلى 12، أو 0 لتحديد سنة بدون شهر ويوم.
day	int32 يوم من الشهر يجب أن يكون من 1 إلى 31 وصالحًا للسنة والشهر، أو 0 لتحديد سنة بمفردها أو سنة وشهر لا يُحتسَب فيها اليوم.

DayOfWeek

يمثّل يومًا من أيام الأسبوع.

عمليات التعداد
DAY_OF_WEEK_UNSPECIFIED	يوم الأسبوع غير محدّد.
MONDAY	الاثنين
TUESDAY	الثلاثاء
WEDNESDAY	الأربعاء
THURSDAY	الخميس
FRIDAY	الجمعة
SATURDAY	السبت
SUNDAY	الأحد

الفاصل الزمني

يمثّل فاصلًا زمنيًا، ويتم ترميزه كبداية طابع زمني (شاملة) ونهاية طابع زمني (حصرية).

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

الحقول
start_time	Timestamp اختيارية: بداية الفاصل الزمني الشاملة في حال تحديده، يجب أن يكون الطابع الزمني الذي يتطابق مع هذا الفاصل الزمني هو نفسه أو بعد البدء.
end_time	Timestamp اختيارية: نهاية الفاصل الزمني الحصرية إذا تم تحديد طابع زمني مطابق لهذا الفاصل الزمني، يجب أن يكون قبل النهاية.

رقم الهاتف

عنصر يمثّل رقم هاتف، وهو مناسب لتنسيق بيانات واجهة برمجة التطبيقات.

يُرجى العِلم أنّ هذا التمثيل:

• يجب عدم استخدامها لتنسيق رقم هاتف خاص بلغة معيّنة، مثل "‎[phone] ext. 123"

• غير مصمّمة لتخزين البيانات بكفاءة

• قد لا تكون مناسبة للاتصال - يجب استخدام مكتبات متخصصة (راجِع المراجع) لتحليل الرقم لهذا الغرض

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

على سبيل المثال، في Java، سيكون هذا الإجراء على النحو التالي:

com.google.type.PhoneNumber wireProto =
    com.google.type.PhoneNumber.newBuilder().build();
com.google.i18n.phonenumbers.Phonenumber.PhoneNumber phoneNumber =
    PhoneNumberUtil.getInstance().parse(wireProto.getE164Number(), "ZZ");
if (!wireProto.getExtension().isEmpty()) {
  phoneNumber.setExtension(wireProto.getExtension());
}

المراجع: - https://github.com/google/libphonenumber

الحقول
extension	string رقم الهاتف الإضافي لا يتمّ توحيد الإضافة في اقتراحات الاتحاد الدولي للاتصالات، باستثناء أنّه يتمّ تعريفها على أنّها سلسلة من الأرقام التي يبلغ طولها 40 رقمًا كحدّ أقصى. بالإضافة إلى الأرقام، قد يتم تخزين بعض أحرف الاتصال الأخرى هنا، مثل "," (للإشارة إلى الانتظار) أو "#". يُرجى العِلم أنّه لا تتوفّر حاليًا مناطق تستخدم أرقامًا لاحقة ذات رموز قصيرة، لذا لا يتم عادةً ضبط هذا الحقل إلا مع رقم E.164. ويتم الاحتفاظ به بشكل منفصل عن رقم E.164 للسماح بإضافة أرقام إضافية إلى الرمز القصير في المستقبل.
حقل الربط kind مطلوب. إما رقم عادي أو رمز قصير. قد تتم إضافة حقول جديدة إلى oneof أدناه في المستقبل، لذا على العملاء تجاهل أرقام الهواتف التي لم يتم ضبط أيّ من الحقول التي تم ترميزها وفقًا لها. يمكن أن يكون kind واحدًا فقط مما يلي:
e164_number	string رقم الهاتف، الذي يتم تمثيله بعلامة الإضافة (‎+‎) في البداية، متبوعًا برقم هاتف يستخدم تنسيق ITU E.164 المُبسَّط الذي يتألف من رمز الاتصال بالبلد (من رقم واحد إلى 3 أرقام) ورقم المشترك، بدون مسافات أو تنسيق إضافي على سبيل المثال: - صحيح: "[phone]" - غير صحيح: "[phone] x123". يحدّ تنسيق E.164 الصادر عن الاتحاد الدولي للاتصالات من عدد أرقام هذا الحقل إلى 12 رقمًا، ولكن في الواقع، لا تلتزم بعض البلدان بهذا العدد، لذلك خفّضنا هذا الحدّ هنا. لا يُسمح باستخدام أرقام محلية فقط. المراجع: - https://www.itu.int/rec/T-REC-E.164-201011-I - https://en.wikipedia.org/wiki/E.164. - https://en.wikipedia.org/wiki/List_of_country_calling_codes
short_code	ShortCode رمز قصير المراجع: - https://en.wikipedia.org/wiki/Short_code

ShortCode

عنصر يمثّل رمزًا قصيرًا، وهو رقم هاتف يكون عادةً أقصر بكثير من أرقام الهواتف العادية ويمكن استخدامه لتوجيه الرسائل في أنظمة الرسائل القصيرة المتعددة الوسائط والرسائل القصيرة، بالإضافة إلى الاتصال المختصر (على سبيل المثال "أرسِل رسالة نصية إلى 611 لمعرفة عدد الدقائق المتبقية في خطتك").

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

الحقول
region_code	string مطلوب. رمز المنطقة وفقًا لمعيار BCP-47 للموقع الجغرافي الذي يمكن فيه إجراء مكالمات إلى هذا الرمز القصير، مثل "US" و "BB" المراجع: - http://www.unicode.org/reports/tr35/#unicode_region_subtag
number	string مطلوب. أرقام الرمز القصير، بدون علامة الإضافة (‎+‎) أو رمز الاتصال بالبلد على سبيل المثال، "611".

PostalAddress

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

في الاستخدام العادي، يتم إنشاء عنوان من خلال إدخال المستخدم أو من خلال استيراد البيانات الحالية، وذلك حسب نوع العملية.

نصائح حول إدخال العنوان أو تعديله: - استخدِم تطبيق مصغّر لعنوان متوافق مع الترجمة والنشر في جميع أنحاء العالم، مثل https://github.com/google/libaddressinput) - يجب عدم عرض عناصر واجهة مستخدِم لإدخال الحقول أو تعديلها خارج البلدان التي يتم استخدام هذا الحقل فيها.

لمزيد من الإرشادات حول كيفية استخدام هذا المخطّط، يُرجى الاطّلاع على: https://support.google.com/business/answer/6397478.

الحقول
revision	int32 مراجعة المخطّط لـ PostalAddress يجب ضبط هذه القيمة على 0، وهي آخر مراجعة. يجب أن تكون جميع المراجعات الجديدة متوافقة مع المراجعات القديمة.
region_code	string مطلوب. رمز منطقة CLDR للبلد أو المنطقة التي يقع فيها العنوان ولا يتم استنتاج ذلك مطلقًا، ويعود الأمر للمستخدم للتأكّد من صحة القيمة. اطّلِع على https://cldr.unicode.org/ وhttps://www.unicode.org/cldr/charts/30/supplemental/territory_information.html للاطّلاع على التفاصيل. على سبيل المثال، "CH" لسويسرا.
language_code	string اختيارية: رمز اللغة BCP-47 لمحتوى هذا العنوان (إذا كان معروفًا) غالبًا ما تكون هذه هي لغة واجهة المستخدم لنموذج الإدخال، أو من المتوقّع أن تتطابق مع إحدى اللغات المستخدَمة في بلد/منطقة العنوان أو ما يعادلها من الترجمة الصوتية. ويمكن أن يؤثر ذلك في التنسيق في بلدان معيّنة، ولكنه ليس ضروريًا لصحة البيانات ولن يؤثّر مطلقًا في أي عمليات تحقّق أو عمليات أخرى غير ذات صلة بالتنسيق. إذا لم تكن هذه القيمة معروفة، يجب حذفها (بدلاً من تحديد قيمة تلقائية قد تكون غير صحيحة). على سبيل المثال: "zh-Hant" و"ja" و"ja-Latn" و"en".
postal_code	string اختيارية: الرمز البريدي للعنوان لا تستخدم بعض البلدان الرموز البريدية أو تطلب إدخالها، ولكن في البلدان التي يتم استخدامها فيها، قد تؤدي إلى إجراء عمليات تحقق إضافية مع أجزاء أخرى من العنوان (على سبيل المثال، التحقّق من الولاية/الرمز البريدي في الولايات المتحدة).
sorting_code	string اختيارية: رمز ترتيب إضافي خاص بكل بلد لا يتم استخدام هذا الإجراء في معظم المناطق. في البلدان التي يتم فيها استخدام هذه السمة، تكون القيمة إما سلسلة مثل CEDEX، متبوعة اختياريًا برقم (مثل CEDEX 7)، أو رقمًا فقط يمثّل "رمز القطاع" (جامايكا) أو "مؤشر منطقة التسليم" (ملاوي) أو "مؤشر مكتب البريد" (مثل ساحل العاج).
administrative_area	string اختيارية: أعلى تقسيم فرعي إداري يُستخدَم للعناوين البريدية لبلد أو منطقة. على سبيل المثال، يمكن أن يكون ذلك ولاية أو مقاطعة أو إقليمًا أو محافظة. في إسبانيا تحديدًا، يشير هذا الحقل إلى المقاطعة وليس إلى المنطقة الذاتية الحكم (على سبيل المثال، "برشلونة" وليس "كتالونيا"). لا تستخدم العديد من البلدان منطقة إدارية في العناوين البريدية. على سبيل المثال، في سويسرا، يجب عدم تعبئة هذا الحقل.
locality	string اختيارية: يشير هذا الحقل بشكل عام إلى جزء المدينة/البلدة من العنوان. أمثلة: مدينة أمريكية، بلدية إيطالية، مدينة بريدية في المملكة المتحدة في مناطق العالم التي لا تكون فيها المواقع الجغرافية محدّدة جيدًا أو لا تتوافق مع هذه البنية بشكل جيد، اترك حقل locality فارغًا واستخدِم address_lines.
sublocality	string اختيارية: البلدة الفرعية للعنوان على سبيل المثال، يمكن أن تكون هذه الأحياء أو المناطق الإدارية أو المقاطعات.
address_lines[]	string سطور عناوين غير منظَّمة تصف المستويات الدنيا للعنوان بما أنّ القيم في address_lines لا تحتوي على معلومات عن النوع وقد تحتوي أحيانًا على قيم متعدّدة في حقل واحد (على سبيل المثال "القاهرة، مصر")، من المهم أن يكون ترتيب الأسطر واضحًا. يجب أن يكون ترتيب سطور العنوان هو "ترتيب المظروف" للبلد أو المنطقة التي يقع فيها العنوان. في الأماكن التي يمكن أن يختلف فيها ذلك (مثل اليابان)، يتم استخدام address_language لجعلها واضحة (على سبيل المثال، "ja" للترتيب من الأكبر إلى الأصغر و "ja-Latn" أو "en" للترتيب من الأصغر إلى الأكبر). بهذه الطريقة، يمكن اختيار السطر الأكثر تحديدًا من العنوان استنادًا إلى اللغة. يتكون الحد الأدنى المسموح به من التمثيل الهيكلي للعنوان من رمز منطقة مع جميع المعلومات المتبقية في سطور العنوان. يمكن تنسيق عنوان كهذا تقريبًا جدًا بدون ترميز جغرافي، ولكن لا يمكن إجراء أيّ استدلال دلالي بشأن أيّ من مكوّنات العنوان إلى أن يتم حلّه جزئيًا على الأقل. إنّ إنشاء عنوان يحتوي فقط على region_code وaddress_lines، ثمّ ترميزه جغرافيًا هو الطريقة المُقترَحة للتعامل مع العناوين غير المنظَّمة تمامًا (بدلاً من تخمين أجزاء العنوان التي يجب أن تكون مواقع جغرافية أو مناطق إدارية).
recipients[]	string اختيارية: المستلِم في العنوان قد يحتوي هذا الحقل، في حالات معيّنة، على معلومات متعددة الأسطر. على سبيل المثال، قد يحتوي على معلومات "العنوان المُرسَل إليه".
organization	string اختيارية: اسم المؤسسة في العنوان

TimeOfDay

يمثّل وقتًا من اليوم. التاريخ والمنطقة الزمنية غير مهمّين أو تم تحديدهما في مكان آخر. قد تختار واجهة برمجة التطبيقات السماح بالثواني الكبيسة. الأنواع ذات الصلة هي google.type.Date وgoogle.protobuf.Timestamp.

الحقول
hours	int32 ساعات اليوم بتنسيق 24 ساعة يجب أن تكون أكبر من أو تساوي 0 ويجب أن تكون عادةً أقل من أو تساوي 23. قد تختار واجهة برمجة التطبيقات السماح بالقيمة "24:00:00" لسيناريوهات مثل وقت إغلاق النشاط التجاري.
minutes	int32 دقائق الساعة يجب أن تكون القيمة أكبر من أو تساوي 0 وأصغر من أو تساوي 59.
seconds	int32 ثوانٍ من الدقيقة يجب أن تكون أكبر من أو تساوي 0 ويجب أن تكون عادةً أقل من أو تساوي 59. قد تسمح واجهة برمجة التطبيقات بالقيمة 60 إذا كانت تسمح بالثواني الكبيسة.
nanos	int32 أجزاء من الثانية، بالنانوسثانية يجب أن تكون أكبر من أو تساوي 0 وأقل من أو تساوي 999,999,999.

TimeZone

يمثّل منطقة زمنية من قاعدة بيانات المناطق الزمنية في IANA.

الحقول
id	string المنطقة الزمنية لقاعدة بيانات المناطق الزمنية في IANA على سبيل المثال، "America/New_York".
version	string اختيارية: رقم إصدار قاعدة بيانات المناطق الزمنية في IANA على سبيل المثال، "2019a".