Package google.digitalassetlinks.v1

אינדקס

דפי חשבון

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

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

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

רשימה

rpc List(ListRequest) returns (ListResponse)

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

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

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

נכס אפליקציה

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

שם השדה סוג תיאור
package_name string נכסי אפליקציות ל-Android מזוהים באופן טבעי לפי שם החבילה שלהם ב-Java. למשל, אפליקציית מפות 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 של המחרוזת הזו ולייצג את התוצאה כמחרוזת הקסדצימלית (כלומר, ייצוג הקסדצימלי באותיות גדולות של כל 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, צור איתנו קשר תחילה.

בקשה לרשימה

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

שם השדה סוג תיאור
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

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

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

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

ההתבטאות

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

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

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

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

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

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

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

דוגמה: 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/ (השדה אינו תואם) נדרש