מדריך למתחילים: הגדרת Document AI API

במדריך הזה מפורטים כל השלבים להגדרה ולשימוש ב-Document AI.

היכרות עם מסוף Google Cloud

מסוף Google Cloud console הוא ממשק משתמש לדפדפן שבאמצעותו מקצים, מגדירים, מנהלים ומנטרים את המערכות שמשתמשות במוצרי Google Cloud . בעזרת מסוף Google Cloud אפשר להגדיר ולנהל משאבים ב-Document AI.

יצירת פרויקט

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

  • קבוצה של שותפי עריכה
  • ממשקי API מופעלים (ומשאבים אחרים)
  • כלי מעקב
  • פרטי חיוב
  • אימות ובקרות גישה
  • מעבדים של Document AI

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

בדף לבחירת הפרויקט במסוף Google Cloud , בוחרים פרויקט ב- Google Cloud או יוצרים אותו.

תפקידים שנדרשים כדי לבחור או ליצור פרויקט

  • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
  • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (יצירת פרויקטים) (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

כניסה לדף לבחירת הפרויקט

הפעלת ה-API

צריך להפעיל את Document AI API בפרויקט. למידע נוסף על הפעלת ממשקי API, ראו את התיעוד של Service Usage.

מפעילים את Document AI API.

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק 'שימוש בשירות'' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

להפעלת ה-API

הפעלת החיוב

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

מוודאים שהחיוב מופעל בפרויקט Google Cloud .

קבלת התפקידים הנדרשים

כדי לקבל את ההרשאות שנדרשות למתן גישה של חשבון ראשי לקבצים ב-Cloud Storage, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM אדמין לניהול אחסון (roles/storage.admin) בקטגוריה. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

מיקומים

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

הגדרת מיקום באמצעות API

בכל פעם ששולחים בקשת עיבוד באמצעות ה-API, צריך לציין את המיקום של המעבד. לדוגמה, אם המעבד שלכם מוגדר לאחסון ולעיבוד של הנתונים שלכם באיחוד האירופי, צריך להשתמש ב-URI‏ eu-documentai.googleapis.com באופן הבא:

Process
  • https://eu-documentai.googleapis.com/v1/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:process
  • https://eu-documentai.googleapis.com/v1beta3/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:process
batchProcess
  • https://eu-documentai.googleapis.com/v1/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:batchProcess
  • https://eu-documentai.googleapis.com/v1beta3/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:batchProcess

התקנה של ספריית הלקוח של Document AI API

יש שלוש אפשרויות לשליחת קריאה ל-Document AI API:

ספריות הלקוח זמינות בכמה שפות נפוצות. מידע על התקנת ספריות הלקוח זמין במאמר ספריות לקוח של Document AI API.

התקנה והפעלה של Google Cloud CLI

‫ה-CLI של gcloud הוא קבוצת כלים שבעזרתם אפשר לנהל משאבים ואפליקציות שמתארחים ב- Google Cloud.

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

התקינו את ה-CLI של Google Cloud. אחר כך, אתחלו את ה-CLI של Google Cloud באמצעות הפקודה הבאה: 

gcloud init

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

מגדירים אימות

כל יישום לקוח שמשתמש ב-API צריך לעבור אימות ולקבל גישה למשאבים הנדרשים. הגדרת האימות משתנה בהתאם לסביבה שבה אתם עובדים: סביבת פיתוח מקומית או סביבת ייצור. מידע נוסף זמין במאמר בנושא הגדרה של Application Default Credentials.

בוחרים את הכרטיסיות הרלוונטיות לאופן שבו תכננתם לגשת ל-API:

gcloud

התקינו את ה-CLI של Google Cloud. אחר כך, אתחלו את ה-CLI של Google Cloud באמצעות הפקודה הבאה: 

gcloud init

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

ספריות לקוח

כדי להשתמש בספריות לקוח בסביבת פיתוח מקומית, מתקינים ומפעילים את ה-CLI של gcloud, ואז מגדירים את Application Default Credentials באמצעות פרטי הכניסה של המשתמש.

  1. התקינו את ה-CLI של Google Cloud.

  2. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

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

    gcloud auth application-default login

    אם אתם משתמשים ב-Cloud Shell, אין צורך לבצע את הפעולה הזו.

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

למידע נוסף, ראו הגדרת ADC לסביבת פיתוח מקומית במאמרי העזרה בנושא אימות Google Cloud .

REST

כדי להשתמש ב-API בארכיטקטורת REST בסביבת פיתוח מקומית, צריך להשתמש בפרטי הכניסה שאתם נותנים ל-CLI של gcloud.

    התקינו את ה-CLI של Google Cloud.

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

מידע נוסף מופיע במאמר אימות לשימוש ב-REST במסמכי האימות של Google Cloud .

למידע נוסף על הגדרת אימות בסביבת ייצור, ראו את המאמר בנושא הגדרת Application Default Credentials לקוד שפועל ב- Google Cloud במאמרי העזרה בנושא אימות ב- Google Cloud .

מידע על תפקידים

כשחשבון משתמש מאומת מנסה לגשת למשאב, IAM בודק אם לחשבון המשתמש יש את ההרשאות הנדרשות. Google Cloudכדי לתת הרשאות לחשבונות משתמשים, צריך להקצות תפקידים במדיניות ההרשאות ב-IAM. מידע נוסף על חשבונות משתמשים, תפקידים, משאבים ומדיניות הרשאות מופיע במאמר סקירה כללית של IAM.

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

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

הגדרת גישה לקבצים בפרויקטים שונים

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

כדי לאפשר גישה בין פרויקטים, צריך להעניק את התפקיד 'צפייה באובייקט אחסון' (roles/storage.objectViewer) לסוכן השירות של Document AI, כמו שמוצג באיור הבא.

setup-1

דוגמה

  • נניח שבפרויקט א' מתארחים מעבדים של Document AI, ואופציונלית מתארחת קטגוריה שבה נכתב פלט המעבד.
  • פרויקט ב' הוא הבעלים של הקטגוריה שמכילה קובצי קלט למעבדים של Document AI.

  • כדי שיהיה אפשר לגשת לקבצים בפרויקט ב' מפרויקט א', צריך להעניק את התפקיד 'צפייה באובייקט אחסון' (roles/storage.objectViewer) לסוכן השירות של Document AI בפרויקט א' עבור קטגוריית הקלט בפרויקט ב'.

    setup-2

מידע נוסף על IAM ועל התפקיד 'צפייה באובייקטים ב-Storage' זמין במאמר תפקידי IAM ל-Cloud Storage.

חשבונות שירות מובנים

סוכן שירות של Document AI פועל לפי מוסכמת מתן השמות הבאה:

service-{project number}@gcp-sa-prod-dai-core.iam.gserviceaccount.com

לדוגמה: service-361747088407@gcp-sa-prod-dai-core.iam.gserviceaccount.com

setup-3

השלבים הבאים: תרחישים לדוגמה

אחרי שמפעילים את Document AI API, אפשר ליצור מעבדים של Document AI ולהשתמש בהם. סוג המעבד שהכי מתאים לכם תלוי בתרחיש השימוש.

הבא
העשרה