‫Images API לשירותים בחבילה מדור קודם

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

שירות התמונות יכול לקבל נתוני תמונה ישירות מהאפליקציה, או להשתמש בערך של Cloud Storage. (שירות התמונות יכול להשתמש גם בערך Cloud Blobstore, אבל מומלץ להשתמש ב-Cloud Storage).

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

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

כשמציגים תמונות מ-Cloud Storage, ‏ Images API משתמש בחשבון שירות שמנוהל על ידי Google, ‏ dynamic_image_service@system.gserviceaccount.com, כדי לאחזר את התמונה. בדרך כלל הפעולה הזו מתבצעת בשבילכם, אבל אם לחשבון השירות הזה אין את התפקיד Storage Object Viewer בדלי, יכול להיות שתיתקלו בשגיאות 403 Forbidden לסירוגין. המצב הזה קורה כשהתמונה לא זמינה במטמון של Google וצריך לאחזר אותה מהמאגר המקורי.

כדי להעניק את ההרשאה הנדרשת, מריצים את הפקודה הבאה של gcloud:

gcloud storage buckets add-iam-policy-binding gs://[BUCKET_NAME] \
  --member=serviceAccount:dynamic_image_service@system.gserviceaccount.com \
  --role=roles/storage.objectViewer

Image Service API

טרנספורמציות זמינות של תמונות

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

שינוי גודל

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

סיבוב

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

היפוך אופקי

אפשר להפוך את התמונה אופקית.

היפוך אנכי

אפשר להפוך את התמונה אנכית.

חיתוך

אפשר לחתוך את התמונה באמצעות תיבת תוחמת נתונה.

יותר מזל משכל

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

פורמטים של תמונות

השירות מקבל נתוני תמונות בפורמטים JPEG, ‏ PNG, ‏ WEBP, ‏ GIF (כולל GIF מונפש), ‏ BMP, ‏ TIFF ו-ICO. אפשר להחזיר תמונות שעברו שינוי בפורמטים JPEG,‏ WEBP ו-PNG.

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

שינוי תמונות

שירות התמונות יכול להשתמש בערך מ-Cloud Storage או מ-Blobstore כמקור התמונה לשינוי. יש שתי דרכים לבצע טרנספורמציה לתמונות:

  1. השימוש במחלקה Image() מאפשר לבצע טרנספורמציות פשוטות בתמונות, כמו חיתוך, היפוך וסיבוב.
  2. השימוש ב- get_serving_url() מאפשר לשנות את הגודל של התמונות ולחתוך אותן באופן דינמי, כך שלא צריך לאחסן בשרת תמונות בגדלים שונים. השיטה הזו מחזירה כתובת URL שמשמשת להצגת התמונה, והשינויים בתמונה מקודדים בכתובת ה-URL הזו. הפונקציה הזו מניחה שהתמונה לא משתנה. אם היא משתנה אחרי שקיבלתם את כתובת ה-URL, יכול להיות שתקבלו תוצאות לא צפויות משימוש בכתובת ה-URL.

שימוש בכיתה Image()

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

כדי לשנות תמונה מ-Cloud Storage או מ-Blobstore, מעבירים לו ערך blobstore.BlobKey במקום להגדיר את הארגומנט image_data של הקונסטרוקטור Image עם נתוני התמונה, ומגדירים את הארגומנט blob_key למפתח Blobstore שהערך שלו הוא התמונה. שאר ה-API מתנהג כצפוי. השיטה execute_transforms() מחזירה את התוצאה של השינויים, או מעלה שגיאה LargeImageError אם התוצאה גדולה מהגודל המקסימלי של 32 מגה-בייט.

שימוש ב- get_serving_url()

השיטה get_serving_url() מאפשרת ליצור כתובת URL קבועה וייעודית לתמונה שמאוחסנת ב-Cloud Storage או ב-Blobstore.

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

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

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

http://lhx.ggpht.com/randomStringImageId

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

  • ‫=sxx‏ xx הוא מספר שלם מ-0 עד 2,560 שמייצג את האורך, בפיקסלים, של הצד הארוך ביותר של התמונה. לדוגמה, הוספת =s32 משנה את גודל התמונה כך שהמימד הארוך ביותר שלה יהיה 32 פיקסלים.
  • ‫=sxx-c‏ xx הוא מספר שלם מ-0 עד 2560 שמייצג את גודל התמונה החתוכה בפיקסלים, ו--c אומר למערכת לחתוך את התמונה.
# Resize the image to 32 pixels (aspect-ratio preserved)
http://lhx.ggpht.com/randomStringImageId=s32

# Crop the image to 32 pixels
http://lhx.ggpht.com/randomStringImageId=s32-c

תמונות ושרת הפיתוח

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

אפשר להשתמש ב-Pillow או בממשק Python ל-ImageMagick כדי לשנות את הגודל של התמונות, להמיר אותן ולערוך אותן.

הערה לגבי מחיקה

כדי להפסיק את הצגת התמונה שמאוחסנת ב-Cloud Storage או ב-Blobstore, צריך לקרוא לשיטה פונקציית delete_serving_url().

מומלץ להימנע ממחיקה ישירה של תמונות ב-Cloud Storage או ב-Blobstore, כי פעולה כזו עלולה להשאיר אותן נגישות דרך כתובת ה-URL להצגה.

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

מכסות, מגבלות ותמחור

נכון לעכשיו, אין חיוב נוסף על שימוש ב-Images API. אפשר לעיין בדף המחירים של App Engine.

כל בקשה ל-Images API נספרת במכסת הקריאות ל-Image Manipulation API. אפליקציה יכולה לבצע כמה טרנספורמציות של תמונה בקריאה אחת של API.

הנתונים שנשלחים לשירות התמונות נספרים במכסת הנתונים שנשלחים אל (Images) API. הנתונים שמתקבלים משירות התמונות נספרים במכסת הנתונים שמתקבלים מ-(Images) API.

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

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

בנוסף למכסות, ההגבלות הבאות חלות על השימוש בשירות Images:

הגבלה סכום
גודל הנתונים המקסימלי של התמונה שנשלחת לשירות ‫32 מגה-בייט
גודל הנתונים המקסימלי של תמונה שהתקבלה מהשירות ‫32 מגה-בייט
הגודל המקסימלי של תמונה שנשלחת או מתקבלת מהשירות ‫50 מגה-פיקסל