שליחת בקשת API ל-Vision

Cloud Vision API הוא API בארכיטקטורת REST שמשתמש בפעולות HTTP POST כדי לבצע ניתוח נתונים בתמונות שאתם שולחים בבקשה. ממשק ה-API משתמש ב-JSON גם לבקשות וגם לתשובות.

סיכום

הבקשות הן בקשות POST אל https://vision.googleapis.com/v1/images:annotate.
עליכם לאמת את הבקשות.
גוף הבקשה נראה כך. התגובות נראות בערך כך, אבל השדות משתנים בהתאם לסוג ההערה שאתם מוסיפים.
כך שולחים בקשה באמצעות cURL.
יש גם ספריות לקוח.
רוצים לראות הדגמה קצרה? פשוט גוררים ומשחררים!

נקודת קצה (endpoint)

‫Vision API מורכב מנקודת קצה אחת (https://vision.googleapis.com/v1/images) שתומכת ב-method אחת של בקשת HTTP ‏ (annotate):

POST https://vision.googleapis.com/v1/images:annotate

אימות

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

פורמט בקשת JSON

גוף בקשת ה-POST מכיל אובייקט JSON, שמכיל רשימה אחת של requests, שבעצמה מכילה אובייקט אחד או יותר מסוג AnnotateImageRequest:

{
  "requests":[
    {
      "image":{
        "content":"/9j/7QBEUGhvdG9...image contents...eYxxxzj/Coa6Bax//Z"
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}

כל בקשה:

חייב להכיל רשימה של requests.

ברשימה requests:

‫image מציין את קובץ התמונה. אפשר לשלוח אותו כמחרוזת בקידוד base64, כמיקום קובץ ב-Cloud Storage או ככתובת URL שנגישה לכולם. פרטים נוספים זמינים במאמר בנושא הוספת תמונה.
‫features מפרט את סוגי האנוטציות שיש לבצע בתמונה. אפשר לציין סוג אחד או כמה סוגים, וגם את maxResults שיוחזר לכל סוג.
‫imageContext (לא מוצג בדוגמה שלמעלה) מציין רמזים לשירות שיעזרו בהערות: תיבות תוחמות, שפות ויחסי גובה-רוחב של רמזים לחיתוך.

העלאת התמונה

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

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

{
  "requests":[
    {
      "image":{
        "content":"/9j/7QBEUGhvdG9zaG9...image contents...fXNWzvDEeYxxxzj/Coa6Bax//Z"
      },
      "features":[
        {
          "type":"FACE_DETECTION",
          "maxResults":10
        }
      ]
    }
  ]
}

הוראות לקידוד בפלטפורמות שונות מפורטות במאמר בנושא קידוד Base64.

כ-URI של Cloud Storage. מעבירים את ה-URI המלא כערך של image.source.imageUri:
```
{
  "requests":[
    {
      "image":{
        "source":{
          "imageUri":
            "gs://bucket_name/path_to_image_object"
        }
      },
      "features":[
        {
          "type":"LABEL_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}
```
הקובץ ב-Cloud Storage צריך להיות נגיש לשיטת האימות שבה אתם משתמשים. אם אתם משתמשים במפתח API, הקובץ צריך להיות נגיש לכולם. אם משתמשים בחשבון שירות, המשתמש שיצר את חשבון השירות צריך להיות בעל גישה לקובץ.
ככתובת URL מסוג HTTP או HTTPS שנגישה לציבור. מעבירים את כתובת ה-URL כערך של image.source.imageUri:
```
{
  "requests":[
    {
      "image":{
        "source":{
          "imageUri":
            "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png"
        }
      },
      "features":[
        {
          "type":"LOGO_DETECTION",
          "maxResults":1
        }
      ]
    }
  ]
}
```
כשמאחזרים תמונות מכתובות URL של HTTP/HTTPS, ‏ Google לא יכולה להבטיח שהבקשה תושלם. יכול להיות שהבקשה תיכשל אם המארח שצוין דוחה את הבקשה (למשל, בגלל ויסות בקשות או מניעת DoS), או אם Google מווסתת את הבקשות לאתר כדי למנוע שימוש לרעה. מומלץ לא להסתמך על תמונות שמתארחות חיצונית באפליקציות לייצור.

פורמט תגובת JSON

annotate הבקשה מקבלת תגובת JSON מהסוג AnnotateImageResponse. למרות שהבקשות דומות לכל סוג של תכונה, התשובות לכל סוג של תכונה יכולות להיות שונות מאוד. מידע מלא זמין בהפניית Vision API.

בדוגמה הבאה מוצגת תגובה של זיהוי תוויות לתמונה שמופיעה בהמשך:

{
  "responses": [
    {
      "labelAnnotations": [
        {
          "mid": "/m/0bt9lr",
          "description": "dog",
          "score": 0.97346616
        },
        {
          "mid": "/m/09686",
          "description": "vertebrate",
          "score": 0.85700572
        },
        {
          "mid": "/m/01pm38",
          "description": "clumber spaniel",
          "score": 0.84881884
        },
        {
          "mid": "/m/04rky",
          "description": "mammal",
          "score": 0.847575
        },
        {
          "mid": "/m/02wbgd",
          "description": "english cocker spaniel",
          "score": 0.75829375
        }
      ]
    }
  ]
}

ספריות לקוח

‫Google מספקת ספריות לקוח בכמה שפות תכנות כדי לפשט את התהליך של בנייה ושליחה של בקשות, וקבלת תשובות וניתוח שלהן.

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

שליחת בקשת API ל-Vision קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.