תחילת העבודה

במסמך הזה מפורט מידע הרקע הנדרש לשימוש ב-Google Site Verification API.

מבוא

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

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

סקירה כללית

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

כל הקריאות ל-API צריכות לקבל הרשאה ממשתמש מאומת, וכל הקריאות ל-API מתבצעות בהקשר של החשבון של המשתמש המאומת.

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

לפני שמתחילים

קבל חשבון Google

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

הכרת התהליך של אימות האתר

אם אינך מכיר את המושגים של Google Site Verification API, עליך לקרוא את המסמך הזה, להתנסות בממשק המשתמש לאימות ולקרוא את מאמרי העזרה המשויכים לפני שמתחילים לתכנת.

מידע נוסף על אישור בקשות

כל בקשה שהאפליקציה שלך שולחת אל Google Site Verification API חייבת לכלול אסימון הרשאה. אסימון ההרשאה גם מזהה את האפליקציה שלכם ב-Google.

הסבר על פרוטוקולים של הרשאות

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

הרשאת בקשות עם פרוטוקול OAuth 2.0

כל הבקשות ל-Google Site Verification API חייבות לקבל הרשאה ממשתמש מאומת.

הפרטים או ה"זרימה" של תהליך ההרשאה עם OAuth 2.0 עשויים להשתנות מעט, בהתאם לסוג האפליקציה שאתם מפתחים. התהליך הכללי הבא חל על כל סוגי האפליקציות:

  1. כשיוצרים את האפליקציה, רושמים אותה באמצעות Google API Console. לאחר הרישום, Google מספקת נתונים שיהיו דרושים לכם מאוחר יותר, כמו מזהה לקוח וסוד לקוח.
  2. מפעילים את Google Site Verification API במסוף Google API. (אם ה-API לא מופיע ב-API Console, דלגו על השלב הזה).
  3. כשהאפליקציה צריכה גישה לנתונים של משתמשים, היא מעבירה ל-Google בקשת גישה בהיקף ספציפי.
  4. Google מציגה למשתמש מסך הסכמה ומבקשת לאשר לאפליקציה לשלוח בקשה לחלק מהנתונים שלו.
  5. אם המשתמש מסכים, האפליקציה מקבלת מ-Google אסימון גישה לטווח קצר.
  6. האפליקציה מבקשת את נתוני המשתמש ומצרפת לבקשה את אסימון הגישה.
  7. אם Google תקבע שהבקשה והאסימון תקפים, היא תחזיר את הנתונים המבוקשים.

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

פרטים על היקף ההרשאות OAuth 2.0 עבור Google Site Verification API:

היקף משמעות
https://www.googleapis.com/auth/siteverification גישת קריאה מלאה לאתרים מאומתים קיימים, יכולת לאמת אתרים חדשים.
https://www.googleapis.com/auth/siteverification.verify_only יכולת לאמת אתרים חדשים, אין גישת קריאה לאתרים מאומתים קיימים.

כדי לבקש גישה באמצעות פרוטוקול OAuth 2.0, האפליקציה שלכם זקוקה למידע על ההיקף ולמידע ש-Google מספקת בזמן רישום האפליקציה (כמו מזהה לקוח וסוד לקוח).

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

רקע של Google Site Verification API

מושגים

אפשר להשתמש ב-Google Site Verification API כדי ליצור בעלות של משתמש על משאבי האינטרנט הבאים:

  • דומיין: דומיין או תת-דומיין. הבעלים של דומיין נחשבים לבעלים של הדומיין. הבעלים של כל האתרים ותת-הדומיינים בדומיין הזה. לדוגמה, הבעלים הישירים של bar.com נחשב גם לבעלים העקיף של foo.bar.com.
  • אתר: כתובת URL שתואמת לדומיין הבסיס ולנתיב של אתר. הבעלים של אתר נחשב לבעלים של כל האתרים שתחתיו. לדוגמה, הבעלים של "http://www.example.com/site" נחשב גם הוא לבעלים של "http://www.example.com/site/subsite".

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

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

מגבלות

מטעמי אבטחה ובעיות טכניות, Google Site Verification API אוכף כמה הגבלות על אופן השימוש בו:

  • גישה לנתונים עבור משתמשים מאומתים בלבד: כל הפעולות מחייבות אימות והרשאה של המשתמש.
  • אימות רק למשתמשים מאומתים: ה-API יכול לאמת את הבעלות על אתרים או דומיינים רק בחשבון המאומת. עם זאת, משתמש מאומת יכול להאציל את הבעלות למשתמשים אחרים לאחר אימות הבעלות שלו על האתר. שים לב שכל הבעלים מקבלים הודעה באימייל בכל פעם שמתבצע שינוי ברשימת הבעלות.
  • כתובות URL מנורמלות ושמות דומיינים בלבד. ממשק ה-API של אימות אתר Google אינו תומך בקידוד IDN (שם דומיין בינלאומי). חשוב להקפיד לנרמל את כל כתובות ה-URL, שמות הדומיינים והדומיינים של כתובות האימייל בהתאם למערכת התווים הסטנדרטית של שמות הדומיינים (RFC 1034 §3.5) באמצעות קידוד ב-Punycoding.

שיטות ואסימונים לאימות

ה-API מספק קריאות לשלבי האימות הנפרדים:

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

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

שיטת האימות לדומיין

יש שתי שיטות אימות שזמינות לדומיינים:

DNS_CNAME

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

DNS_TXT

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

מידע נוסף זמין במרכז העזרה בנושא שיטת אימות ה-DNS.

שיטות לאימות אתרים

יש שלוש שיטות אימות זמינות לאתרים:

קובץ
האפליקציה שלך מציבה את האסימון בפורמט של קובץ באתר של הבעלים. צריך ליצור קובץ שהשם שלו יהיה תואם למחרוזת האסימון, עם התוכן הבא: 
google-site-verification: token

לדוגמה, אם משתמש הוא הבעלים של האתר http://www.example.com/, והאסימון המוחזר הוא google12cfc68677988bb4.html, צריך פשוט ליצור קובץ בכתובת http://www.example.com/google12cfc68677988bb4.html (ברמה העליונה של האתר), עם התכנים הבאים:

google-site-verification: google12cfc8677988bb4.html

מידע נוסף זמין במרכז העזרה בנושא שיטת אימות הקבצים.

Meta

האפליקציה שלך מוסיפה את האסימון בצורת תג <meta> HTML, בתוך הרכיב <head> של קובץ ברירת המחדל (index.html, default.html וכו') ברמה העליונה של אתר הבעלים. קובץ HTML עם אסימון לאימות מטא-נתונים עשוי להיראות כך:

<html>
  <head>
    <title>Awesome Dive Sites</title>
    <meta name="google-site-verification" content="-dhsoFQadgDKJR7BsB6bc1j5yfqjUpg_b-1pFjr7o3x" />
  </head>
  <body>
    ...

מידע נוסף זמין במרכז העזרה על שיטת האימות באמצעות מטא.

ניתוח נתונים

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

Tag Manager

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

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

מודל נתונים

משאב אינטרנט

Google Site Verification API מחיל סמנטיקה של REST (HTTP GET, POST וכו') על ישויות שנקראות משאבי אינטרנט. משאב אינטרנט הוא אתר או דומיין ששייך למשתמש המאומת.

הנה דוגמה למשאב אינטרנט:

{
  "owners": [
    "myself@example.com",
    "another@example.com"
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

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

האובייקט site מכיל את כתובת ה-URL או את שם הדומיין של משאב האינטרנט, ואת סוג המשאב. אתרים מצוינים מסוג SITE; דומיינים מצוינים עם הסוג INET_DOMAIN.

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

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

איסוף משאבי אינטרנט

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

כפי שצוין קודם בקטע מגבלות, לא ניתן לגשת למשאבי אינטרנט ששייכים למשתמשים שהם לא המשתמש המאומת דרך Site Verification API.