שימוש ב-Datastream API

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

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

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

אתם משתמשים ב-Datastream API גם באופן עקיף, כשאתם משתמשים באחת מהדרכים הבאות לניהול מופעים:

היתרון בשימוש בשיטות האלה, במיוחד ב-Google Cloud console, הוא שהן יכולות לפשט מאוד את הניהול של הגדרות הקישוריות הפרטית, פרופילי החיבור והסטרימינג (בהתאם לתרחיש השימוש). אם אתם רק מתחילים להשתמש ב-Datastream, מומלץ להתחיל עם אחד מהכלים האלה לפני שתעבדו ישירות עם API בארכיטקטורת REST.

הפעלת ה-API

כדי להשתמש ב-Datastream API, צריך להפעיל אותו:

המסוף

  1. מפעילים את Datastream API.
  2. בוחרים את הפרויקט הרצוי.
  3. לוחצים על המשך.

gcloud

  1. מזינים את הפקודה הבאה כדי להציג את מזהי הפרויקטים של Google Cloudהפרויקטים שלכם: 
    gcloud projects list
  2. מגדירים את פרויקט ברירת המחדל: 
    gcloud config set project YOUR_PROJECT_ID
  3. מפעילים את Datastream API: 
    gcloud services enable datastream.googleapis.com

הרשאות

כדי להשתמש ב-Datastream API, אתם צריכים לקבל את ההרשאות הנדרשות. ההרשאות האלה כוללות:

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

‫Google Cloud כולל את הפתרון 'ניהול זהויות והרשאות גישה (IAM)', שמאפשר לתת גישה פרטנית יותר למשאבים ספציפיים ב- Google Cloud ולמנוע גישה לא רצויה למשאבים אחרים. אפשר לקבל ולהגדיר הרשאות ל-Datastream באמצעות Google Cloud Console, שיטות IAM של ה-API או Google Cloud SDK. מידע נוסף זמין במאמר הענקה, שינוי וביטול גישה למשאבים.

דוגמאות ל-API

בדפים הבאים של מסמכי Datastream מופיעות דוגמאות לשימוש ב-Datastream API עם cURL:

העברת נתוני JSON מקובץ

כשמשתמשים ב-API עם cURL, צריך לספק ערכי מאפיינים באמצעות שורת הפקודה. אם אתם עובדים עם ערכים רגישים כמו סיסמאות או מפתחות אבטחה, מסוכן לספק אותם בשורת הפקודה. כדי לשפר את האבטחה, אתם יכולים ליצור קובץ שמכיל את נתוני ה-JSON לקריאה ל-API, ולציין את הנתיב לקובץ בשורת הפקודה.

כדי לספק נתוני JSON לקריאה ל-API של cURL מקובץ:

  1. יוצרים קובץ שמכיל את כל מה שמוקף במירכאות בודדות בשדה --data.

    צריך לכלול את הסוגריים המסולסלים, אבל לא את המירכאות הבודדות.

  2. בשורת הפקודה, מציינים את הנתיב לקובץ, עם התו @ לפניו, כפרמטר --data:

    --data @<path-to-file>/<filename>

    לדוגמה, כדי ליצור פרופיל חיבור למקור MySQL, אפשר ליצור קובץ בשם request.json עם התוכן הבא:

    {
  "displayName": "my MySQL connection profile",
  "mysql": {
    "host": "10.11.12.13",
    "port": 3306,
    "username": "myusername",
    "password": "mypassword"
  }
}

    אחר כך, משתמשים בפקודת ה-cURL הבאה בשורת הפקודה:

    curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data @./request.json \
     -X POST \
     https://datastream.googleapis.com/v1/projects/myProject/locations/myLocation/connectionProfiles?connectionProfileId=myMySQLconnectionprofile

עבודה עם קריאות ל-API שפועלות לאורך זמן

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

אתם יכולים להשתמש ב-Datastream API כדי לנהל פעולות. למשל:

‫Datastream ו-Google APIs Discovery Service

‫Google APIs Discovery Service הוא שירות שמאפשר לכם לגלות Google APIs. לדוגמה, כשמשתמשים בכלי Google APIs Explorer , משתמשים ב-Discovery Service.

בשירות Discovery, ‏ Datastream מיוצג כ-datastream (לדוגמה: https://datastream.googleapis.com/$discovery/rest?version=v1).