בקשות קנוניות

בקשות קנוניות מגדירות את רכיבי הבקשה שהמשתמש צריך לכלול כשהוא שולח ל-Cloud Storage בקשות עם חתימה מאומתת V4, כמו למשל כתובות URL חתומות.

סקירה כללית

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

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

בקשה קנונית מבטיחה שכאשר הבקשה מתקבלת ב-Cloud Storage, היא תוכל לחשב את אותה החתימה שאתם חישבתם. אם הגרסה שלכם והגרסה המחושבת על-ידי Cloud Storage לא תואמות, הבקשה תיכשל.

מבנה

לבקשות קנוניות יש את המבנה הבא, כולל שימוש בשורות חדשות בין כל רכיב:

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

פעלים של HTTP

בקשות חתומות יכולות להשתמש בפעלים הבאים של HTTP, שחובה לציין אותם כחלק מהבקשה הקנונית:

DELETE
GET
HEAD
‫POST¹
PUT

¹ אפשר להשתמש בכתובות URL חתומות רק בבקשות של POST שמתחילות העלאה שניתן להמשיך. למידע נוסף, ראו שימוש בכתובות URL חתומות עם העלאות שניתן להמשיך.

נתיב המשאב

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

לדוגמה, אם כתובת ה-URL של Cloud Storage היא https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg, הנתיב למשאב הוא /example-bucket/cat-pics/tabby.jpeg.

אם משתמשים בכתובת URL חלופית של Cloud Storage, כמו https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg, הנתיב למשאב הוא /cat-pics/tabby.jpeg.

לנקודות קצה נוספות של כתובות URL שאפשר להשתמש בהן עם כתובות URL חתומות, ראו נקודות קצה של בקשות של API בפורמט XML.

כשמגדירים את נתיב המשאב, צריך לקודד באחוזים את התווים השמורים הבאים: ?=!#$&'()*+,:;@[]" כל קידוד אחר באחוזים בכתובת ה-URL צריך להיכלל גם בנתיב המשאב.

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

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

מחרוזת השאילתה היא כל מה שמופיע אחרי סימן השאלה (?) בסוף נתיב המשאב.

לדוגמה, אם כתובת ה-URL של Cloud Storage היא https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project, מחרוזת השאילתה היא generation=1360887697105000&userProject=my-project.

כשיוצרים את מחרוזת השאילתה הקנונית:

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

פרמטרים נדרשים למחרוזת שאילתה

רוב הפרמטרים של מחרוזת השאילתה נוספים לפי הצורך, אבל חובה לכלול את הפרטים הבאים בבקשה הקנונית כשמתכוונים להשתמש בה כדי ליצור כתובת URL חתומה:

‫X-Goog-Algorithm: האלגוריתם שבו משתמשים כדי לחתום על כתובת ה-URL. הערכים המותרים הם GOOG4-RSA-SHA256 ו-GOOG4-HMAC-SHA256.
‫X-Goog-Credential: פרטי הכניסה שבהם משתמשים כדי לחתום על כתובת ה-URL. פרטי הכניסה כוללים גורם מאשר ואת היקף פרטי הכניסה בפורמט AUTHORIZER%2FCREDENTIAL_SCOPE. הגורם המאשר יכול להיות שם חשבון שירות או מזהה גישה למפתח HMAC.
‫X-Goog-Date: התאריך והשעה שבהם אפשר להתחיל את השימוש בכתובת ה-URL החתומה בפורמט הבסיסי YYYYMMDD'T'HHMMSS'Z' של ISO 8601.
‫X-Goog-Expires: משך החיים של כתובת ה-URL החתומה, הנמדד בשניות מ-X-Goog-Date. ערך התפוגה הארוך ביותר הוא 604,800 שניות (7 ימים).
‫X-Goog-SignedHeaders: רשימת שמות של כותרות המופרדות באמצעות נקודה-פסיק, המוגדרות בבקשה הקנונית. הן נקראות גם כותרות חתומות. ‫host חייב להיות אחד משמות הכותרות.

בהמשך, צריך להשתמש בפרמטרים של מחרוזת השאילתה בכתובת ה-URL החתומה עצמה, יחד עם הפרמטר X-Goog-Signature של מחרוזת השאילתה, המכיל את החתימה המאמתת את הבקשה.

כותרות קנוניות

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

כותרות קנוניות יכולות לכלול כותרות בהתאמה אישית וגם כותרות הרחבה המתחילות ב-x-goog-.

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

משתמשים באותיות קטנות בשמות של כל הכותרות.
אפשר למיין את הכותרות לפי שם הכותרת באמצעות מיון לקסיקוגרפי לפי ערך מיקום תו (code point).
מפרידים כל כותרת באמצעות שורה חדשה (\n).
כדאי לבטל שמות כפולים של כותרות על ידי יצירת שם כותרת אחד עם רשימת ערכים המופרדים בפסיקים. חשוב לוודא שאין רווחים לבנים בין הערכים, ולוודא שהסדר של הרשימה המופרדת בפסיקים תואם לסדר שבו הכותרות מופיעות בבקשה. מידע נוסף מופיע ב-RFC 7230 סעיף 3.2.
מחליפים רצף של רווחים לבנים או שורות חדשות (CRLF או LF) ברווח יחיד. מידע נוסף על רצף של רווחים לבנים מופיע ב-RFC 7230, סעיף ‎3.2.4.‎.
מסירים רווחים לבנים מסביב לנקודתיים שמופיעות אחרי שם הכותרת.

לדוגמה, שימוש בכותרת בהתאמה אישית x-goog-acl: private בלי להסיר את הרווח אחרי הנקודתיים מחזיר שגיאת 403 Forbidden, כי חתימת הבקשה שאתם מחשבים לא תואמת לחתימה ש-Google מחשבת.

דוגמה

אם יש לכם את קבוצת הכותרות הבאה:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

יצירת הכותרות הקנוניות בבקשה הקנונית תהיה:

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

כותרות קנוניות נדרשות

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

‫host: ה-URI המשמש לגישה ל-Cloud Storage.
כותרות עם הקידומת x-goog-. הכותרת היחידה שאפשר לכלול ככותרת קנונית היא x-goog-content-sha256.
כותרות עם הקידומת x-amz-. הכותרת היחידה שאפשר לכלול ככותרת קנונית היא x-amz-content-sha256.

כותרות חתומות

כותרת חתומה היא החלק של השם בכותרת קנונית.

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

דוגמה

אם יש לכם את קבוצת הכותרות הבאה:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

המבנה של הכותרות החתומות בבקשה הקנונית יהיה:

content-type;host;x-goog-meta-reviewer

מטען ייעודי (payload)

אם הבקשה הקנונית תשמש ליצירת כתובת URL חתומה, הערך צריך להיות המחרוזת UNSIGNED-PAYLOAD.
אם הבקשה הקנונית תשמש כחלק מבקשה שיש בה כותרת Authorization:
- כדאי להשתמש ב-UNSIGNED-PAYLOAD אם רוצים לאפשר מטענים ייעודיים (payloads) שרירותיים כחלק מהבקשה.
- אם רוצים לאפשר רק מטען ייעודי (payload) ספציפי, הערך הזה צריך להיות גיבוב מסוג SHA-256 עם אותיות קטנות, המקודד בקידוד הקסדצימלי של המטען הייעודי (payload) הרצוי. כדי לחייב מטען ייעודי (payload) ריק, צריך להשתמש במחרוזת ריקה כקלט לפונקציית הגיבוב (hash). דוגמה למטען ייעודי (payload) מגובב (במקרה הזה, מטען ייעודי (payload) ריק):
```
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

דוגמה

הדוגמה הבאה היא דוגמה לבקשה קנונית שנוצרה באופן תקין, השורות החדשות מופיעות כשורות חדשות בפועל ולא כ-\n:

GET
/example-bucket/tabby.jpeg

host:storage.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

המאמרים הבאים

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