Package google.digitalassetlinks.v1

אינדקס

הצהרות

שירות ה-API הזה מציג 'הצהרות', שהן כלי הרכב שבהם משתמשים בעלי נכסים כדי לפרסם מידע על קישורי הנכסים שלהם. ניתן להשתמש ב-API כדי לאחזר הצהרות בדרך פשוטה ומאובטחת, ללא צורך לקבל את ההצהרות ישירות מהמקורות.

כל ההצהרות שהוחזרו על ידי ה-API הזה בוצעו בשם נכסים דיגיטליים (למשל, אתרים או אפליקציות ל-Android) בקשר לנכסים דיגיטליים אחרים. כל הצהרה מכילה נכס מקור, נכס יעד וקשר אחד או יותר.

הקשר מתאר את הקשר בין שני הנכסים כפי שנכס המקור תבע עליהם בעלות. דוגמה ליחסים כאלה היא הענקת הרשאות או הרשאות.

רשימה

rpc List(ListRequest) returns (ListResponse)

מאחזרת רשימה של כל ההצהרות ממקור נתון שתואמות למחרוזת היעד וההצהרה שצוינו.

ה-API מבטיח שכל ההצהרות עם נכסי מקור מאובטחים, כמו אתרי HTTPS או אפליקציות ל-Android, בוצעו באופן מאובטח על ידי הבעלים של הנכסים האלה, כפי שמתואר במפרט העיצוב הטכני של Digital Asset Links. באופן ספציפי, כדאי לזכור שעבור אתרים לא מאובטחים (כלומר, שבהם כתובת ה-URL מתחילה ב-http:// במקום ב-https://), לא ניתן לבצע התחייבות זו.

הפקודה List שימושית במיוחד במקרים שבהם לקוח ה-API רוצה לדעת את כל הדרכים שבהן שני נכסים קשורים זה לזה, או למנות את כל קשרי הגומלין מנכס מקור מסוים. דוגמה: תכונה שעוזרת למשתמשים לנווט לפריטים קשורים. כשאפליקציה לנייד פועלת במכשיר, התכונה הזו מאפשרת לנווט בקלות לאתר האינטרנט או לפרופיל Google+ המקביל.

AndroidAppAsset

מיועד לתיאור נכס אפליקציה ל-Android.

שם השדה סוג תיאור
package_name string נכסים של אפליקציות ל-Android מזוהים באופן טבעי לפי שם החבילה שלהם ב-Java. לדוגמה, אפליקציית מפות Google משתמשת בשם החבילה com.google.android.apps.maps. חובה
certificate CertificateInfo

מכיוון שאין אכיפה גלובלית של הייחודיות של שם חבילה, אנחנו דורשים גם אישור חתימה, שבשילוב עם שם החבילה מאפשר לזהות אפליקציה באופן ייחודי.

מפתחות החתימה של אפליקציות מסוימים עוברים רוטציה, כך שמפתחות שונים עשויים לחתום עליהם במשך הזמן. אנחנו מתייחסים אליהם כאל נכסים נפרדים, כי אנחנו משתמשים (שם החבילה, אישור) בתור המזהה הייחודי. בדרך כלל לא אמורה להיות בעיה כזו, כי שתי הגרסאות של האפליקציה יספקו את אותה הצהרה או הצהרות דומות. עם זאת, יהיה צורך לעדכן נכסים אחרים שכוללים הצהרות לגבי האפליקציה לאחר רוטציית מפתח.

(שימו לב שהתחביר לפרסום ולשליחת שאילתות לגבי הצהרות מכילים סוכר תחבירי כדי לאפשר לכם לציין בקלות אפליקציות שמוכרות באמצעות אישורים מרובים). חובה

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 של המחרוזת הזו ולייצג את התוצאה כמחרוזת הקסדצימלית (כלומר, ייצוגים הקסדצימליים באותיות רישיות של כל 8 תווים, מופרדים בנקודתיים).

הנכס

מזהה באופן ייחודי את הנכס.

נכס דיגיטלי הוא ישות באינטרנט שאפשר לזהות אותה וניתן לטפל בה, והיא בדרך כלל מספקת שירות או תוכן מסוים. דוגמאות לנכסים: אתרים, אפליקציות ל-Android, פידים של Twitter ודפי Plus.

שם השדה סוג תיאור
שדה איחוד, רק אחד מהערכים הבאים:
web WebAsset צריך להגדיר אם זהו נכס אינטרנט.
android_app AndroidAppAsset צריך להגדיר אם זהו נכס אפליקציה ל-Android.

CheckRequest

הודעה שמשמשת כדי לבדוק אם קיים קישור לנכס ספציפי.

שם השדה סוג תיאור
source Asset המקור שמארח את רשימת ההצהרות. הפעולה הזו משמשת לניתוב של הקריאה Check() למקור הנכון.
relation string

מחרוזת שאילתה של הקשר.

אנחנו מזהים קשרים עם מחרוזות בפורמט <kind>/<detail>, כאשר <kind> חייב להיות אחת מקבוצה של קטגוריות מטרות מוגדרות מראש, ו-<detail> היא מחרוזת אלפאנומרית קטנה שמתארת את התרחיש הספציפי של ההצהרה.

ברשימה הנוכחית של הקשרים הנתמכים אפשר לעיין במסמכי התיעוד של ה-API.

כדי ששאילתה תתאים לקישור לנכס, צריכה להיות התאמה מדויקת גם מחרוזות הקשר של השאילתה וגם של הקישור לנכס.

דוגמה: שאילתה עם קשר delegate_permission/common.handle_all_urls תואמת לקישור נכס עם קשר delegate_permission/common.handle_all_urls.
target Asset נכס היעד של הדוח.

CheckResponse

הודעת תשובה לקריאה של CheckAssetLinks.

שם השדה סוג תיאור
linked bool הערך צריך להיות True אם הנכסים שצוינו בבקשה מקושרים באמצעות הקשר שצוין בבקשה. חובה
max_age Duration מרגע הצגת הבקשה, משך הזמן שבו התגובה צריכה להיחשב כחוקית, ולכן אי אפשר לבצע עדכונים נוספים. חובה
debug_string string

הודעה קריא לאנשים, שמכילה מידע שנועד לעזור למשתמשי הקצה להבין את התוצאה, לשחזר אותה ולנפות באגים.

ההודעה תהיה באנגלית ובשלב הזה אנחנו לא מתכננים להציע תרגומים.

לתשומת ליבכם, אין כל ערובה לגבי התוכן או הפורמט של המחרוזת הזו. כל היבט עשוי להשתנות ללא הודעה מוקדמת. מומלץ לא לנסות לנתח את הנתונים האלה באופן פרוגרמטי. אם לדעתך עליך לעשות זאת מפני שהמידע הדרוש לך לא נחשף בדרך אחרת על ידי ה-API, ראשית צור אתנו קשר.

ListRequest

הודעה שמשמשת לבקשת כל ההצהרות הידועות שיש להן מקור ויחס שצוינו.

שם השדה סוג תיאור
source Asset המקור שמארח את רשימת ההצהרות. הוא משמש להפניית הבקשה List() למקור הנכון. חובה
relation string

השתמשו רק בשיוכים שתואמים ליחס שצוין.

עיינו בהודעה Statement כדי לקבל הגדרה מפורטת של מחרוזות קשר.

כדי ששאילתה תתאים להצהרה, צריך להתקיים אחד מהתנאים הבאים:

  • גם מחרוזות הקשר של השאילתה וגם מחרוזות היחסים של ההצהרה תואמות בדיוק, או
  • מחרוזת הקשר של השאילתה ריקה או חסרה.

דוגמה: שאילתה עם קשר delegate_permission/common.handle_all_urls תואמת לקישור נכס עם קשר delegate_permission/common.handle_all_urls.

ListResponse

הודעת תשובה לשיחת הרשימה.

שם השדה סוג תיאור
statements Statement רשימה של כל ההצהרות התואמות שנמצאו.
max_age Duration מרגע הצגת הבקשה, משך הזמן שבו התגובה צריכה להיחשב כחוקית, ולכן אי אפשר לבצע עדכונים נוספים. חובה
debug_string string

הודעה קריא לאנשים, שמכילה מידע שנועד לעזור למשתמשי הקצה להבין את התוצאה, לשחזר אותה ולנפות באגים.

ההודעה תהיה באנגלית ובשלב הזה אנחנו לא מתכננים להציע תרגומים.

לתשומת ליבכם, אין כל ערובה לגבי התוכן או הפורמט של המחרוזת הזו. כל היבט עשוי להשתנות ללא הודעה מוקדמת. מומלץ לא לנסות לנתח את הנתונים האלה באופן פרוגרמטי. אם לדעתך עליך לעשות זאת מפני שהמידע הדרוש לך לא נחשף בדרך אחרת על ידי ה-API, ראשית צור אתנו קשר.

ההתבטאות

מיועד לתיאור הצהרה אמינה שנוצרה בנוגע לקשר בין נכס מקור לנכס יעד.

ההצהרות תמיד מתבצעות על ידי נכס המקור, באופן ישיר או על ידי הענקת גישה לרשימת הצהרות ששמורה במקום אחר.

הגדרות מפורטות יותר של דפי חשבון ונכסים זמינות בדף הנחיתה של תיעוד ה-API.

שם השדה סוג תיאור
source Asset לכל הצהרה יש נכס מקור. חובה
relation string

הקשר מזהה את השימוש בהצהרה כפי שהתכוונתם על ידי הבעלים של נכס המקור (כלומר, האדם או הישות שפרסמו את ההצהרה). לכל הצהרה מלאה יש קשר.

אנחנו מזהים קשרים עם מחרוזות בפורמט <kind>/<detail>, כאשר <kind> חייב להיות אחת מקבוצה של קטגוריות מטרות מוגדרות מראש, ו-<detail> היא מחרוזת אלפאנומרית קטנה שמתארת את התרחיש הספציפי של ההצהרה.

ברשימה הנוכחית של הקשרים הנתמכים אפשר לעיין במסמכי התיעוד של ה-API.

דוגמה: delegate_permission/common.handle_all_urls REQUIRED
target Asset לכל הצהרה יש נכס יעד. חובה

WebAsset

מתאר נכס אינטרנט.

שם השדה סוג תיאור
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/ (היציאה לא תואמת) REQUIRED