Package google.digitalassetlinks.v1

الفهرس

كشوفات الحساب

تعرض خدمة واجهة برمجة التطبيقات هذه "كشوفات الحساب"، وهي المركبات التي يستخدمها مالكو مواد العرض لنشر معلومات حول روابط مواد العرض الخاصة بهم. ويمكن استخدام واجهة برمجة التطبيقات لاسترداد البيانات بطريقة بسيطة وآمنة، بدون الحاجة إلى الحصول على كشوفات الحساب مباشرةً من المصادر.

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

توضّح العلاقة العلاقة بين مادتي العرض كما هو مطلوب في مادة العرض المصدر. ومن أمثلة هذه العلاقات تفويض الامتيازات أو الأذونات.

قائمة

rpc List(ListRequest) returns (ListResponse)

لاسترداد قائمة بجميع العبارات من مصدر معين تطابق السلسلة المحددة للهدف والعبارة.

تضمن واجهة برمجة التطبيقات أن جميع البيانات التي تحتوي على مواد عرض آمنة للمصدر، مثل المواقع الإلكترونية التي تستخدم بروتوكول HTTPS أو التطبيقات المتوافقة مع Android، قد تم إنشاؤها بطريقة آمنة من قِبل مالك تلك الأصول، كما هو موضّح في مواصفات التصميم الفني لروابط مواد العرض الرقمية. وعلى وجه التحديد، بالنسبة إلى المواقع الإلكترونية غير الآمنة (أي الموقع الذي يبدأ فيه عنوان URL بـ http:// بدلاً من https://)، لا يمكن تقديم هذا الضمان.

يكون الأمر List مفيدًا جدًا في الحالات التي يريد فيها عميل واجهة برمجة التطبيقات معرفة جميع الطرق التي ترتبط بها مادتا عرض، أو إحصاء جميع العلاقات من مادة عرض مصدر معينة. مثال: ميزة تساعد المستخدمين على الانتقال إلى العناصر ذات الصلة. عند تشغيل تطبيق جوّال على أحد الأجهزة، فستسهل هذه الميزة التنقل إلى موقع الويب أو الملف الشخصي المقابل في +Google.

مادة عرض AndroidApp

وصف مادة عرض تطبيق Android.

اسم الحقل النوع الوصف
package_name string يتم التعرُّف على مواد عرض تطبيقات Android بشكل طبيعي من خلال اسم حزمة جافا. على سبيل المثال، يستخدم تطبيق "خرائط Google" اسم الحزمة com.google.android.apps.maps. مطلوب
certificate CertificateInfo

ونظرًا لعدم وجود تفرُّد عالمي عن تفرُّد اسم الحزمة، نتطلب أيضًا شهادة توقيع تحدد اسم التطبيق بشكل فريد مع اسم الحزمة.

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

(لاحظ أن تركيبات النشر وطلب البحث عن العبارات تحتوي على السكر النحوي لتتيح لك تحديد التطبيقات المعروفة بشهادات متعددة.) مطلوب

معلومات الشهادة

يصف شهادة X509.

اسم الحقل النوع الوصف
sha256_fingerprint string

الملف المرجعي للشهادة SHA-265 الكبير. من خلال شهادة PEM، يمكن الحصول عليها على النحو التالي:

$ keytool -printcert -file $CERTFILE | grep SHA256:
SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
    42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5

أو هكذا:

$ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
    16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5

في هذا المثال، ستكون محتويات هذا الحقل 14:6D:E9:83:C5:73: 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF: 44:E5.

إذا لم تكن هذه الأدوات متوفرة لك، يمكنك تحويل شهادة PEM إلى تنسيق DER، ثم حساب تجزئة SHA-256 لتلك السلسلة وتمثيل النتيجة كسلسلة سداسية عشرية (بمعنى التمثيل السداسي العشري الكبير لكل ثُمانية، مفصولة بعلامات النقطتين).

مادة العرض

يحدد مادة العرض بشكل فريد.

مادة العرض الرقمية هي كيان يمكن التعرّف عليه ويمكن التعرّف عليه ويمكن الوصول إليه على الإنترنت عادةً ما يقدّم بعض الخدمات أو المحتوى. ومن أمثلة مواد العرض مواقع الويب وتطبيقات Android وخلاصات Twitter وصفحات Plus.

اسم الحقل النوع الوصف
حقل الاتحاد، أي واحد مما يلي:
web WebAsset تعيين ما إذا كانت مادة عرض الويب هذه.
android_app AndroidAppAsset تعيين ما إذا كانت مادة عرض تطبيق Android هذه.

طلب فحص

الرسالة المستخدمة للتحقق من وجود رابط مادة عرض معين.

اسم الحقل النوع الوصف
source Asset المصدر الذي يستضيف قائمة العبارات. يُستخدم هذا الخيار لتوجيه استدعاء Check() إلى المصدر الصحيح.
relation string

سلسلة طلب البحث للعلاقة.

نحدّد العلاقات باستخدام سلاسل بالتنسيق <kind>/<detail>، حيث يجب أن تكون <kind> واحدة من مجموعة فئات الأغراض المحددة مسبقًا، و<detail> عبارة عن سلسلة أبجدية رقمية صغيرة حرة الشكل تصف حالة الاستخدام المحددة للعبارة.

ارجع إلى وثائق واجهة برمجة التطبيقات للاطّلاع على القائمة الحالية للعلاقات المتوافقة.

ولكي يتطابق طلب البحث مع رابط مادة عرض، يجب أن تتطابق كلٌّ من سلاسل علاقة طلب البحث ورابط رابط مادة العرض تمامًا.

مثال: يتطابق طلب البحث ذو العلاقة delegate_permission/common.handle_all_urls مع رابط مادة عرض ذو صلة delegate_permission/common.handle_all_urls.
target Asset مادة العرض المستهدفة للكشف.

التحقّق من الرد

رسالة رد على مكالمة CheckAssetLinks.

اسم الحقل النوع الوصف
linked bool يمكنك ضبط هذه القيمة على "صحيح" إذا كانت الأصول المحدّدة في الطلب مرتبطة بالعلاقة المحدّدة في الطلب. مطلوب
max_age Duration من وقت العرض، إلى أي مدى يجب اعتبار الاستجابة صالحة لمنع إجراء المزيد من التحديثات. مطلوب
debug_string string

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

ستكون الرسالة باللغة الإنجليزية، ولا نخطط حاليًا لتقديم أي ترجمات.

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

طلب القائمة

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

اسم الحقل النوع الوصف
source Asset المصدر الذي يستضيف قائمة العبارات. يُستخدم هذا الخيار لتوجيه طلب List() إلى المصدر الصحيح. مطلوب
relation string

استخدِم فقط الارتباطات التي تتطابق مع العلاقة المحدّدة.

يمكنك الاطِّلاع على رسالة Statement للحصول على تعريف تفصيلي لسلاسل العلاقات.

لكي يطابق طلب البحث عبارة، يجب أن يكون أي مما يلي صحيحًا:

  • كل من سلاسل علاقة طلب البحث وعبارة المطابقة التامة، أو
  • سلسلة علاقة طلب البحث فارغة أو ناقصة.

مثال: يتطابق طلب البحث ذو العلاقة delegate_permission/common.handle_all_urls مع رابط مادة عرض ذو صلة delegate_permission/common.handle_all_urls.

سرد الاستجابة

رسالة رد على مكالمة القائمة.

اسم الحقل النوع الوصف
statements Statement قائمة بكل العبارات المطابقة التي تم العثور عليها.
max_age Duration من وقت العرض، إلى أي مدى يجب اعتبار الاستجابة صالحة لمنع إجراء المزيد من التحديثات. مطلوب
debug_string string

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

ستكون الرسالة باللغة الإنجليزية، ولا نخطط حاليًا لتقديم أي ترجمات.

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

العبارات

يصف بيانًا موثوقًا به تم إجراؤه حول العلاقة بين مادة العرض المصدر ومادة العرض المستهدفة.

يتم إعداد كشوفات الحساب دائمًا بواسطة مادة العرض المصدر، إما بشكل مباشر أو من خلال تفويض إلى قائمة كشوفات الحساب المخزنة في مكان آخر.

للحصول على تعريفات أكثر تفصيلاً للبيانات ومواد العرض، يُرجى الرجوع إلى الصفحة المقصودة لوثائق واجهة برمجة التطبيقات.

اسم الحقل النوع الوصف
source Asset لكل كشف مادة عرض مصدر. مطلوب
relation string

تحدد العلاقة استخدام العبارة على النحو المقصود من قِبل مالك مادة العرض المصدر (أي الشخص أو الكيان الذي أصدر العبارة). لكل بيان كامل علاقة.

نحدّد العلاقات باستخدام سلاسل بالتنسيق <kind>/<detail>، حيث يجب أن تكون <kind> واحدة من مجموعة فئات الأغراض المحددة مسبقًا، و<detail> عبارة عن سلسلة أبجدية رقمية صغيرة حرة الشكل تصف حالة الاستخدام المحددة للعبارة.

ارجع إلى وثائق واجهة برمجة التطبيقات للاطّلاع على القائمة الحالية للعلاقات المتوافقة.

مثال: delegate_permission/common.handle_all_urls مطلوب
target Asset لكل كشف مادة عرض مستهدفة. مطلوب

مادة عرض الويب

وصف مادة عرض على الويب

اسم الحقل النوع الوصف
site string

يتم تحديد مواد عرض الويب من خلال عنوان URL يحتوي على المخطط واسم المضيف وأجزاء المنافذ فقط. التنسيق هو

http[s]://<hostname>[:<port>]

يجب أن تكون أسماء المضيف مؤهلة بالكامل: يجب أن تنتهي بنقطة واحدة (".").

يُسمح حاليًا فقط بالمخططين "http" و"https".

يتم تقديم أرقام المنافذ كأرقام عشرية، ويجب حذفها إذا تم استخدام أرقام المنافذ القياسية: 80 لـ http و443 لـ https.

ونُطلق على عنوان URL المحدود هذا اسم "الموقع الإلكتروني". يتم اعتبار جميع عناوين URL التي تتشارك في نفس المخطَّط واسم المضيف والمنفذ جزءًا من الموقع الإلكتروني ولذلك تنتمي إلى مادة عرض الويب.

مثال: تحتوي مادة العرض التي تحتوي على الموقع https://www.google.com على جميع عناوين URL التالية:

  • https://www.google.com/
  • https://www.google.com:443/
  • https://www.google.com/foo
  • https://www.google.com/foo?bar
  • https://www.google.com/foo#bar
  • https://user@password:www.google.com/

ولكن لا يحتوي على عناوين URL التالية:

  • http://www.google.com/ (مخطط خاطئ)
  • https://google.com/ (اسم المضيف غير مطابق)
  • https://www.google.com:444/ (المنفذ غير متطابق) مطلوب