הפעלת ה-API

במסמך הזה נסביר איך להשתמש ב-Google Site Verification API.

הפעלת ה-API

פורמט הבקשה

רוב הפעולות הנתמכות של אימות אתר ממופות ישירות לפעלים מסוג REST HTTP (GET, POST, PUT, DELETE), כפי שמתואר בפעולות של Google Site Verification API.

הפורמט הספציפי למזהי URI של Google Site Verification API הם:

https://www.googleapis.com/siteVerification/v1/webResource/resourceID?parameters

כאשר resourceID הוא המזהה של משאב אינטרנט, parameters הם כל הפרמטרים שצריך להחיל על השאילתה. הפרמטרים שבהם תשתמשו בפועל משתנים בהתאם לפעולה שאתם מבצעים. בנוסף, אם משתמשים ב-OAuth 2.0, צריך להגדיר את access_token בפרמטרים האלה.

בשאילתות של רשימה לא נדרש resourceID, לכן הפורמט הוא:

https://www.googleapis.com/siteVerification/v1/webResource?parameters

אפשר לבצע קריאות לפעולה getToken באמצעות URI ייחודי משלה. הפורמט של קריאה ל-getToken הוא:

https://www.googleapis.com/siteVerification/v1/token?parameters

פורמט נתונים

Google Site Verification API מחזיר נתונים בפורמט JSON.

JSON‏ (JavaScript Object Notation) הוא פורמט נתונים נפוץ בלתי תלוי בשפה, שמספק ייצוג טקסט פשוט של מבני נתונים שרירותיים. למידע נוסף: json.org.

סיכום הפעולות

תוכלו להפעיל שש שיטות שונות לאוספים ולמשאבים ב-Google Site Verification API, כמו שמתואר בטבלה הבאה. כתובות ה-URL של ה-API הן יחסיות ל-https://www.googleapis.com/siteVerification/v1.

פעולה תיאור כתובת URL ותחביר
list

רשימה של כל המשאבים באוסף של המשתמשים המאומתים.

GET /webResource

ראו דוגמה לבקשה של רשימה.
הוספה

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

גוף הבקשה: מידע נוסף זמין בקטע משאב אינטרנט.

פרמטר השאילתה: verificationMethod. שיטת האימות שתשמש לבקשה הזו. ערכים אפשריים: FILE, META, ANALYTICS, TAG_MANAGER, DNS_TXT, DNS_CNAME

POST /webResource

פרטים נוספים זמינים בבקשה להוספה לדוגמה.
הורדה

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

GET /webResource/resourceID

ראו בקשה לדוגמה של get
עדכון

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

גוף הבקשה: מידע נוסף זמין בקטע משאב אינטרנט.

הערות:

  • אי אפשר להסיר את המשתמש המאומת מרשימת הבעלים באמצעות עדכון. במקום זאת, יש להשתמש ב-delete.
  • אפשר להסיר מרשימת הבעלים כל משתמש שאין לו אסימון אימות באתר.

PUT /webResource/resourceID

ראו דוגמה לבקשה לעדכון.
מחיקה

מסירה משאב מהאוסף של המשתמש (מאמתת שהאתר שייך למשתמש).

הערות:

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

DELETE /webResource/resourceID

ראו דוגמה לבקשת מחיקה.
getToken

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

גוף הבקשה:

  • identifier: כתובת האתר או שם הדומיין.
  • type: סוג המשאב שצריך לאמת. ערכים אפשריים: SITE, INET_DOMAIN.
  • verificationMethod: השיטה שבה כדאי להשתמש לאימות האתר. ערכים אפשריים: FILE, META, ANALYTICS, TAG_MANAGER, DNS_TXT, DNS_CNAME

POST /token

ראו דוגמה לבקשת getToken.

דוגמאות לקריאות ל-API

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

אימות אתר חדש

כדי לאמת אתר,

  1. קודם כל מבקשים אסימון אימות באמצעות קריאה ל-getToken.
  2. ממקמים את האסימון באתר בכל שיטה שתבחרו.
  3. מבקשים מ-Google לאמת שהאתר שייך לכם באמצעות הפעולה insert.

getToken (נדרשת הרשאה)

POST https://www.googleapis.com/siteVerification/v1/token?access_token=oauth2-token

בקשה:

POST https://www.googleapis.com/siteVerification/v1/token?access_token=oauth2-token
Content-Type: application/json

{
  "verificationMethod": "FILE",
  "site": {
    "identifier": "http://www.example.com",
    "type": "SITE"
  }
}

תשובה:

{
  "token": "google12cfc68677988bb4.html",
  "method": "FILE"
}

הוספה (נדרשת הרשאה)

POST https://www.googleapis.com/siteVerification/v1/webResource?verificationMethod=FILE&access_token=oauth2-token

בקשה:

POST https://www.googleapis.com/siteVerification/v1/webResource?verificationMethod=FILE&access_token=oauth2-token
Content-Type: application/json

{
  "site": {
    "identifier": "http://www.example.com",
    "type": "SITE"
  }
}

תשובה:

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

אחזור מידע עבור משאבי אינטרנט מאומתים

ניתן לאחזר את הרשימה המלאה של האתרים והדומיינים המאומתים שלך ב-list. אפשר לאחזר מידע של משאב אינטרנט יחיד על ידי שליחת קריאה ל-get.

רשימה (נדרשת הרשאה)

GET https://www.googleapis.com/siteVerification/v1/webResource?access_token=oauth2-token

בקשה:

GET https://www.googleapis.com/siteVerification/v1/webResource?access_token=oauth2-token

תשובה:

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

קבלה (נדרשת הרשאה)

GET https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

בקשה:

GET https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

תשובה:

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

שינוי של פרטי האימות

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

עדכון (נדרשת הרשאה)

PUT https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

בקשה:

PUT https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token
Content-Type: application/json

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

תשובה:

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

מחיקה (נדרשת הרשאה)

DELETE https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

בקשה:

DELETE https://www.googleapis.com/siteVerification/v1/webResource/http%3A%2F%2Fwww.example.com%2F?access_token=oauth2-token

תשובה:

קוד הסטטוס HTTP 204 (ללא תוכן) שמציין הצלחה.