תחילת העבודה

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

מבוא

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

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

סקירה כללית

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

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

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

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

קבל חשבון Google

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

כדאי להכיר את אימות האתר

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

איך מאשרים בקשות?

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

מידע על פרוטוקולים של הרשאות

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

הרשאה לבקשות OAuth 2.0

כל הבקשות לממשק API של אימות אתרים של Google צריכות לקבל הרשאה ממשתמש מאומת.

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

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

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

כאן מופיע מידע על היקף OAuth 2.0 של Google Sites 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'.

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

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

מגבלות

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

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

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

ה-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

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

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

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

Google Analytics

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

Tag Manager

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

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

מודל נתונים

משאב אינטרנט

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

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

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

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

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