מימוש בקשת API

במדריך הזה מתואר תרחיש שימוש שבו אפשר להשתמש ב-Application Integration כדי לנתב ולאחזר מידע לבקשת API של תעבורת נתונים נכנסת (ingress).

סקירה כללית

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

מטרות

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

• מוסיפים טריגר API.
• הוספה והגדרה של משימות Connectors לחיבורים ל-MySQL ול-Oracle.
• מוסיפים ומגדירים משימות של מיפוי נתונים כדי לחלץ ולמפות מטען ייעודי (payload) של API.

עלויות

במדריך הזה משתמשים ברכיבים הבאים של Google Cloud, והשימוש בהם כרוך בתשלום:

• Application Integration
• Integration Connectors
• Secret Manager

ההוראות במדריך הזה נועדו לוודא שהשימוש במשאבים יהיה במסגרת המגבלות של התוכנית בחינם של Google Cloud.

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

לפני שמתחילים

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Create a service account:

1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin). Learn how to grant roles.

2. In the Google Cloud console, go to the Create service account page.

   Go to Create service account
3. Select your project.

4. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

   In the Service account description field, enter a description. For example, Service account for quickstart.

5. Click Create and continue.

6. Grant the following roles to the service account: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

   To grant a role, find the Select a role list, then select the role.

   To grant additional roles, click Add another role and add each additional role.

   Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
7. Click Continue.

8. Click Done to finish creating the service account.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Create a service account:

1. Ensure that you have the Create Service Accounts IAM role (roles/iam.serviceAccountCreator) and the Project IAM Admin role (roles/resourcemanager.projectIamAdmin). Learn how to grant roles.

2. In the Google Cloud console, go to the Create service account page.

   Go to Create service account
3. Select your project.

4. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

   In the Service account description field, enter a description. For example, Service account for quickstart.

5. Click Create and continue.

6. Grant the following roles to the service account: Secret Manager Viewer (roles/secretmanager.viewer), Secret Manager Secret Accessor (roles/secretmanager).

   To grant a role, find the Select a role list, then select the role.

   To grant additional roles, click Add another role and add each additional role.

   Note: The Role field affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later.
7. Click Continue.

8. Click Done to finish creating the service account.

הערה: כל ממשקי Google Cloud API הנדרשים האחרים, כמו Application Integration API, ‏ Secret manager API ו-Connectors API, מופעלים במהלך ההגדרה של Application Integration. לפרטים נוספים, ראה הגדרת Application Integration.

הכנת הסביבה

הגדרת מסד נתונים של MySQL

מתחברים לשרת MySQL ויוצרים מסד נתונים וטבלה לשימוש במדריך הזה. במדריך הזה נעשה שימוש במסד נתונים שמכיל טבלה בשם Customers עם השורות הבאות:

  +-------------+---------------+--------------------+------------------+
  | customer_id | customer_name | customer_emailID   | customer_city    |
  +-------------+---------------+--------------------+------------------+
  |           1 | Alex          | [e-mail]   | New York         |
  |           2 | Dana          | [e-mail]   | Seattle          |
  +-------------+---------------+--------------------+------------------+
  

מידע על יצירה ושימוש במסד נתונים של MySQL זמין במסמכי התיעוד של MySQL.

הגדרה של מסד נתונים של Oracle

מתחברים למסד הנתונים של Oracle ויוצרים טבלה לשימוש במדריך הזה. במדריך הזה נעשה שימוש במסד נתונים שמכיל טבלת SQL בשם Customers עם השורות הבאות:

  +-------------+---------------+--------------------+------------------+
  | customer_id | customer_name | customer_emailID   | customer_city    |
  +-------------+---------------+--------------------+------------------+
  |           1 | Amal          | [e-mail]   | Delhi            |
  |           2 | Hao           | [e-mail]   | Beijing          |
  +-------------+---------------+--------------------+------------------+
  

מידע על יצירה ושימוש במסד נתונים של Oracle זמין במסמכי Oracle.

הגדרת חיבורים

כדי לבצע את המדריך הזה, צריך להגדיר את החיבורים הבאים ב-Integration Connectors:

הערה: מומלץ ליצור את החיבורים הבאים באזור us-central1(lowa).

חיבור ל-MySQL

מגדירים חיבור ל-MySQL ב-Integration Connectors כדי לקבל את ישויות הטבלאות של Customer. מידע על הגדרת מחבר MySQL זמין במאמר מחבר MySQL.

חיבור ל-Oracle DB

מגדירים חיבור ל-Oracle DB ב-Integration Connectors כדי לקבל את ישויות הטבלאות Customer. מידע על הגדרת מחבר MySQL זמין במאמר בנושא מחבר Oracle DB.

יצירת שילוב

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

1. במסוף Google Cloud, עוברים לדף Application Integration.

   מעבר אל Application Integration

2. בתפריט הניווט שמימין, לוחצים על שילובים כדי לפתוח את הדף שילובים.
3. לוחצים על יצירת שילוב ומזינים את הפרטים הבאים בדף יצירת שילוב:
   1. שם השילוב: מזינים api_fulfilment.
   2. תיאור: מזינים Demo integration created for tutorial.
   3. אזור: בוחרים באפשרות us-central1 מתוך רשימת האזורים הנתמכים.
   4. לוחצים על יצירה כדי לפתוח את כלי העריכה של השילוב.

הגדרת טריגר לשילוב

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

במדריך הזה, טריגר API משמש להפעלת השילוב לכל בקשת API חדשה. כדי להוסיף טריגר API לשילוב api_fulfilment ולהגדיר אותו:

1. בכלי לעריכת שילובים, לוחצים על טריגרים כדי להציג רשימה של טריגרים זמינים.
2. לוחצים על הרכיב API trigger (טריגר API) וממקמים אותו בכלי לעריכת שילובים.

   שדות התווית, השם והמזהה של הטריגר ימולאו אוטומטית על ידי Application Integration. מזהה הטריגר הוא מזהה שנוצר על ידי מכונה בפורמט api_trigger/TRIGGER_NAME, והוא משמש בבקשת ה-API.

לא נדרשת הגדרה נוספת לטריגר הזה.

יצירת משתני שילוב

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

1. לוחצים על (החלפת חלונית) בסרגל הניווט של כלי העיצוב כדי להציג את החלונית משתנים.
2. לוחצים על + יצירה ויוצרים את משתני השילוב הבאים:

   שם המשתנה	סוג נתונים	סוג המשתנה
   location	STRING	קלט לשילוב
   customer_id	STRING	קלט לשילוב
   customer_record	JSON	פלט מהשילוב

אחזור נתוני לקוחות ממסד נתונים של MySQL

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

חיבור למסד הנתונים של MySQL

כדי להוסיף ולהגדיר משימת Connectors לאחזור פרטי הלקוחות מטבלת Customers ב-MySQL:

1. בכלי לעריכת שילובים, לוחצים על משימות כדי להציג רשימה של משימות זמינות.
2. לוחצים על הרכיב Connectors (מחברים) וממקמים אותו בעורך השילובים.
3. בוחרים את רכיב המשימה Connectors (מחברים) בכלי העיצוב כדי להציג את חלונית ההגדרות של משימת Connectors.
4. לוחצים על ומשנים את השם של התווית Connectors (מחברים) ל-Fetch MySQL Data.
5. לוחצים על Configure connector (הגדרת מחבר).
6. בדף Connectors Task Editor (עורך משימות של מחברים), מבצעים את הפעולות הבאות:
   1. בקטע בחירת חיבור, בוחרים באזור us-central1.
   2. בוחרים את החיבור ל-Salesforce מתוך רשימת החיבורים הזמינים.
   3. לוחצים על הבא.
   4. בקטע סוג, בוחרים באפשרות ישויות.
   5. בקטע הגדרת ישויות או פעולות, בוחרים באפשרות לקוחות מתוך רשימת הישויות הזמינות, ואז בוחרים באפשרות קבלת בתור פעולה.
   6. לוחצים על סיום כדי להשלים את הגדרת הקישור ולסגור את החלונית.

מיפוי מספר לקוח למחבר MySQL

משימת מיפוי נתונים משמשת למיפוי מזהה הלקוח למחבר MySQL. כדי להוסיף ולערוך את מיפוי הנתונים בשילוב:

1. בכלי לעריכת שילובים, לוחצים על משימות כדי להציג רשימה של משימות זמינות.
2. לוחצים על הרכיב מיפוי נתונים וממקמים אותו בכלי לעריכת שילובים.
3. בוחרים את הרכיב מיפוי נתונים בכלי העיצוב כדי להציג את חלונית הגדרת המשימה.
4. לוחצים על ומשנים את השם של המשימה מיפוי נתונים ל-Map to MySQL.
5. לוחצים על פתיחת הכלי למיפוי נתונים.

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

6. ממפים את משתנה הטריגר —customer_id—המשתנה של השילוב —entityId(Fetch MySQL Data)—משתנה הקלט של המחבר שנוצר אוטומטית.

   אחרי שמסיימים את המיפוי, סוגרים את החלונית. כל השינויים יישמרו אוטומטית.

7. מוסיפים חיבור קצה מהמשימה Map to MySQL למחבר Fetch MySQL Data.

אחזור פרטי לקוח ב-MySQL

כדי לאחזר את פרטי הלקוח ממחבר MySQL:

1. בכלי לעריכת שילובים, לוחצים על משימות כדי להציג רשימה של משימות זמינות.
2. לוחצים על הרכיב מיפוי נתונים וממקמים אותו בכלי לעריכת שילובים.
3. לוחצים על הרכיב מיפוי נתונים בכלי העיצוב כדי לראות את חלונית הגדרת המשימה.
4. לוחצים על ומשנים את השם של המשימה מיפוי נתונים ל-Get MySQL data.
5. לוחצים על פתיחת הכלי למיפוי נתונים.
6. ממפים את משתנה הפלט של MySQL‏ – connectorOutputPayload (Fetch MySQL Data) – למשתנה השילוב customer_record.

   אחרי שמסיימים את המיפוי, סוגרים את החלונית. כל השינויים יישמרו אוטומטית.

7. מוסיפים חיבור קצה מהמחבר Fetch MySQL Data למשימה Get MySQL data.

אחזור נתוני לקוחות ממסד נתונים של Oracle

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

חיבור למסד הנתונים של Oracle

כדי להוסיף ולהגדיר משימת Connectors לאחזור פרטי הלקוחות מטבלת Customers של Oracle:

1. בכלי לעריכת שילובים, לוחצים על משימות כדי להציג רשימה של משימות זמינות.
2. לוחצים על הרכיב Connectors (מחברים) וממקמים אותו בעורך השילובים.
3. בוחרים את רכיב המשימה Connectors (מחברים) בכלי העיצוב כדי להציג את חלונית ההגדרות של משימת Connectors.
4. לוחצים על ומשנים את השם של התווית Connectors (מחברים) ל-Fetch Oracle Data.
5. לוחצים על Configure connector (הגדרת מחבר).
6. בדף Connectors Task Editor (עורך משימות של מחברים), מבצעים את הפעולות הבאות:
   1. בקטע בחירת חיבור, בוחרים באזור us-central1.
   2. בוחרים את החיבור ל-Salesforce מתוך רשימת החיבורים הזמינים.
   3. לוחצים על הבא.
   4. בקטע סוג, בוחרים באפשרות ישויות.
   5. בקטע הגדרת ישויות או פעולות, בוחרים באפשרות לקוחות מתוך רשימת הישויות הזמינות, ואז בוחרים באפשרות קבלת בתור פעולה.
   6. לוחצים על סיום כדי להשלים את הגדרת הקישור ולסגור את החלונית.

מיפוי מספר לקוח למחבר Oracle

כדי להוסיף ולערוך את מיפוי הנתונים בשילוב:

1. בכלי לעריכת שילובים, לוחצים על משימות כדי להציג רשימה של משימות זמינות.
2. לוחצים על הרכיב מיפוי נתונים וממקמים אותו בכלי לעריכת שילובים.
3. בוחרים את הרכיב מיפוי נתונים בכלי העיצוב כדי להציג את חלונית הגדרת המשימה.
4. לוחצים על ומשנים את השם של המשימה מיפוי נתונים ל-Map to Oracle.
5. לוחצים על פתיחת הכלי למיפוי נתונים.
6. ממפים את משתנה הטריגר —customer_id—המשתנה של השילוב —entityId(Fetch Oracle Data)—משתנה הקלט של המחבר שנוצר אוטומטית.

   אחרי שמסיימים את המיפוי, סוגרים את החלונית. כל השינויים יישמרו אוטומטית.

7. מוסיפים קישור Edge מהמשימה Map to Oracle למחבר Fetch Oracle Data.

אחזור פרטי לקוח של Oracle

כדי לאחזר את פרטי הלקוח מהמחבר של Oracle:

1. בכלי לעריכת שילובים, לוחצים על משימות כדי להציג רשימה של משימות זמינות.
2. לוחצים על הרכיב מיפוי נתונים וממקמים אותו בכלי לעריכת שילובים.
3. לוחצים על הרכיב מיפוי נתונים בכלי העיצוב כדי לראות את חלונית הגדרת המשימה.
4. לוחצים על ומשנים את השם של המשימה מיפוי נתונים ל-Get Oracle data.
5. לוחצים על פתיחת הכלי למיפוי נתונים.
6. ממפים את משתנה הפלט של Oracle—connectorOutputPayload (Fetch Oracle Data)—למשתנה השילוב customer_record.

   אחרי שמסיימים את המיפוי, סוגרים את החלונית. כל השינויים יישמרו אוטומטית.

7. מוסיפים חיבור Edge מהמחבר Fetch Oracle Data למשימה Get Oracle data.

הוספת תנאי קצה

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

תנאי הקצה הבא שולט בתהליך השילוב על סמך משתנה השילוב location:

1. מוסיפים חיבור קצה מטריגר API למשימה Map to MySQL עם תנאי הקצה הבא:

     $location$ = "US"

2. מוסיפים עוד חיבור קצה מטריגר API למשימה Map to Oracle עם תנאי הקצה הבא:

     $location$ = "APAC"

זרימת שילוב לדוגמה

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

פרסום השילוב

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

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

בדיקת השילוב

בדיקת השילוב בכלי לעריכת שילובים

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

1. לוחצים על בדיקה בסרגל הכלים של עורך השילוב.

   מופיעה החלונית Test Integration (בדיקת השילוב).

2. מוצגת בקשה להזין את ערכי הבדיקה של משתני הקלט של השילוב. כדי לבצע את הבדיקה הזו:
   • ‫customer_id: מזינים 1.
   • ‫location: מזינים APAC.
3. לוחצים על Test Integration (בדיקת השילוב).

השילוב מתבצע בהצלחה ומוצג ערך הלקוח הבא:

{ 
  "CUSTOMER_ID": 1,
  "CUSTOMER_NAME": "Amal"
  "CUSTOMER_EMAILID": "[e-mail] "
  "CUSTOMER_CITY": "Delhi"
}

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

בדיקה באמצעות קריאה ל-API בארכיטקטורת REST

עכשיו, כשהשילוב פורסם ופועל, אפשר להפעיל אותו באמצעות קריאת ה-REST הבאה מסוג POST:

כתובת ה-URL:‏

https://integrations.googleapis.com/v1/projects/project-name/locations/-/integrations/api_fulfilment:execute 

גוף הבקשה:

{"trigger_id":"api_trigger/api_fulfilment_API_1"}

דוגמה: שליחת בקשת API עם קלט בהתאמה אישית

הערה: בדוגמה הבאה נעשה שימוש ב-curl, שבדרך כלל מותקן מראש במערכות הפעלה של Linux ו-macOS. אם אין לכם את curl, אתם יכולים להוריד אותו מcurl דף ההורדות והגרסאות.

curl -v -X POST -H "Content-Type: application/json" 'https://integrations.googleapis.com/v1/projects/connectors-ip-test/locations/us-central1/integrations/api-fulfillment-integration:execute' -H "Authorization: Bearer $(gcloud auth AUTH_PROFILE)" -d  '{ "triggerId": "api_trigger/api-fulfillment-integration_API_1", "inputParameters": { "customer_id": {"string_value": 1}, "location" : {"string_value" : "US"}} }'

ה-API מחזיר את תגובת ההפעלה של השילוב שמכילה את כל ה-JSON הבא:

  { 
    "CUSTOMER_ID": 2,
    "CUSTOMER_NAME": "Dana"
    "CUSTOMER_EMAILID": "[e-mail] "
    "CUSTOMER_CITY": "Seattle"
  }
  

הסרת המשאבים

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

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