תחילת העבודה עם Cloud Endpoints Frameworks for Java

בדף הזה מוסבר איך להגדיר ולפרוס API לדוגמה, ואיך לשלוח אליו בקשות באמצעות Cloud Endpoints Frameworks for Java. ‫Endpoints Frameworks for Java משולב עם סביבת זמן הריצה הרגילה של Java 8 ב-App Engine. ‫Endpoints Frameworks כולל כלים, ספריות ויכולות שמאפשרים לכם ליצור ממשקי API וספריות לקוח מאפליקציית App Engine.

מטרות

במהלך העבודה עם המדריך, תוכלו להשתמש ברשימת המשימות הכללית הבאה. כדי לשלוח בקשות ל-API, צריך לבצע את כל המשימות.

  1. מגדירים Google Cloud פרויקט. לפני שמתחילים
  2. מתקינים את התוכנה הנדרשת ויוצרים אפליקציית App Engine. מידע נוסף זמין במאמר בנושא התקנה והגדרה של תוכנה נדרשת.
  3. מורידים את הקוד לדוגמה. קבלת קוד לדוגמה
  4. יוצרים קובץ תצורה של OpenAPI. איך מגדירים את Cloud Endpoints
  5. פורסים את ההגדרה של Endpoints כדי ליצור שירות Endpoints. איך פורסים את ההגדרה של נקודות הקצה
  6. מריצים את הדוגמה במחשב. איך מריצים את הדוגמה באופן מקומי
  7. יוצרים קצה עורפי להצגת ה-API ופורסים את ה-API. מידע נוסף זמין במאמר בנושא פריסת קצה העורפי של ה-API.
  8. שליחת בקשה ל-API. שליחת בקשה ל-API
  9. מעקב אחר פעילות ב-API. מידע נוסף זמין במאמר בנושא מעקב אחר פעילות של API.
  10. כדי להימנע מחיובים בחשבון Google Cloud , מידע נוסף זמין בקטע הסרת המשאבים.

עלויות

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

כדי להעריך את ההוצאות בהתאם לתחזית השימוש שלכם, אתם יכולים להיעזר במחשבון העלויות.

משתמשים חדשים של Google Cloud ? יכול להיות שאתם זכאים לתקופת ניסיון בחינם.

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

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

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

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. חשוב לשמור את מזהה הפרויקט כי תצטרכו אותו בהמשך.

התקנה והגדרה של תוכנה נדרשת

  1. אם Java 8 לא מותקן, מורידים את Java Development Kit ‏ (JDK) מ- Oracle ומתקינים אותו. מכיוון ש-Endpoints Frameworks for Java תלוי בסביבת זמן הריצה של Java 8 ב-App Engine סטנדרט,‏ הוא לא תומך בגרסאות אחרות של Java.
  2. אם לא מותקנת אצלכם גרסה Maven 3.3.9 ומעלה, צריך להוריד ולהתקין אותה.

    3. הערה למשתמשי Windows: אם אתם מתקינים את JDK ו-Maven ב-Windows, צריך להתקין אותם בספרייה שאין בה רווח בנתיב. מידע נוסף זמין במאמר בנושא Maven ב-Windows.

  3. אתם צריכים אפליקציה כדי לשלוח בקשות ל-API לדוגמה.

    • משתמשי Linux ו-macOS: במדריך הזה יש דוגמה לשימוש ב-curl, שבדרך כלל מותקן מראש במערכת ההפעלה. אם אין לכם את curl, אתם יכולים להוריד אותו מcurl דף ההורדות והגרסאות.
    • משתמשי Windows: במדריך הזה יש דוגמה לשימוש ב-Invoke-WebRequest, שנתמך ב-PowerShell 3.0 ואילך.
  4. מורידים ומפעילים את Google Cloud CLI.
  5. מריצים את הפקודות הבאות:
    1. מוודאים של-CLI של gcloud יש הרשאה לגשת לנתונים ולשירותים שלכם ב- Google Cloud: 
      gcloud auth login
    2. שימוש ב-Application Default Credentials: 
      gcloud auth application-default login
    3. מתקינים את רכיב app-engine-java של Google Cloud SDK: 
      gcloud components install app-engine-java
    4. מעדכנים לגרסה האחרונה של ה-SDK של Google Cloud וכל הרכיבים: 
      gcloud components update
  6. יוצרים אפליקציית App Engine:
    1. מגדירים את פרויקט ברירת המחדל למזהה הפרויקט. 
      gcloud config set project YOUR_PROJECT_ID

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

    2. בוחרים את האזור שבו רוצים ליצור את אפליקציית App Engine. מריצים את הפקודה הבאה כדי לקבל רשימה של אזורים: 
      gcloud app regions list
    3. יוצרים אפליקציית App Engine באמצעות הפקודה הבאה. מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ואת YOUR_REGION באזור שבו רוצים ליצור את האפליקציה ב-App Engine. Google Cloud 
      gcloud app create \
--project=YOUR_PROJECT_ID \
--region=YOUR_REGION

קבלת הקוד לדוגמה

כדי לשכפל את ה-API לדוגמה מ-GitHub:

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

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples

  2. עוברים לספרייה שמכילה את הקוד לדוגמה:

    cd java-docs-samples/appengine-java8/endpoints-v2-backend

הגדרת נקודות קצה

קוד הדוגמה כולל את כלי Endpoints Frameworks שיוצר קובץ תצורה של OpenAPI שמתאר את ה-API בארכיטקטורת REST של קוד הדוגמה. כדי להגדיר ולבנות את פרויקט Maven לדוגמה, כדי שתוכלו ליצור את קובץ ההגדרות של OpenAPI, פועלים לפי השלבים שמפורטים בקטע הזה.

הוספת מזהה הפרויקט לדוגמה של קוד ה-API

כדי לפרוס את הקוד, צריך להוסיף את מזהה הפרויקט שקיבלתם כשיצרתם את הפרויקט אל pom.xml בדוגמה.

כדי להוסיף את מזהה הפרויקט:

  1. עורכים את הקובץ java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml.

  2. מחפשים את <endpoints.project.id> ומחליפים את YOUR_PROJECT_ID במזהה הפרויקטGoogle Cloud .

    לדוגמה:

    <endpoints.project.id>example-project</endpoints.project.id>

  3. שומרים את השינויים.

יצירת פרויקט לדוגמה

כדי ליצור את הפרויקט:

  1. מוודאים שאתם נמצאים בספרייה java-docs-samples/appengine-java8/endpoints-v2-backend.

  2. מריצים את הפקודה הבאה:

    mvn clean package

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

    [INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 14.846s
[INFO] Finished at: Wed April 13 09:43:09 PDT 2016
[INFO] Final Memory: 24M/331M

יצירת קובץ התצורה של OpenAPI

משתמשים בכלי מספריית Endpoints Frameworks כדי ליצור מסמך OpenAPI שנקרא openapi.json. בקובץ הזה מתואר API בארכיטקטורת REST של קוד לדוגמה.

כדי ליצור את קובץ התצורה של OpenAPI:

  1. מפעילים את הכלי Endpoints Frameworks באמצעות הפקודה הבאה:

    mvn endpoints-framework:openApiDocs

  2. מחכים עד שנוצרת הגדרת התצורה. בסיום התהליך תוצג הודעה דומה לזו:

    OpenAPI document written to target/openapi-docs/openapi.json

    מתעלמים מהודעות על כשל בטעינת מחלקה של כלי רישום סטטי.

פריסת ההגדרה של נקודות הקצה

כדי לפרוס את ההגדרה של Endpoints, משתמשים ב-Service Infrastructure, פלטפורמת השירותים הבסיסית של Google, שמשמשת את Endpoints Frameworks ושירותים אחרים ליצירה ולניהול של ממשקי API ושירותים.

כדי לפרוס את קובץ התצורה:

  1. מוודאים שאתם נמצאים בספרייה java-docs-samples/appengine-java8/endpoints-v2-backend.

  2. פורסים את קובץ התצורה של OpenAPI שנוצר בקטע הקודם:

    gcloud endpoints services deploy target/openapi-docs/openapi.json

פעולה זו יוצרת שירות Endpoints חדש עם השם בפורמט YOUR_PROJECT_ID.appspot.com. השם הזה מוגדר ב-pom.xml ובקבצי הגדרה אחרים שכלולים בדוגמה. שימו לב: כשפורסים את ה-API ב-App Engine, נוצרת רשומת DNS בפורמט השם YOUR_PROJECT_ID.appspot.com, שהוא שם הדומיין שמוגדר במלואו (FQDN) שבו משתמשים כששולחים בקשות ל-API.

במהלך היצירה וההגדרה של השירות, Service Management מציג מידע במסוף. אפשר להתעלם מהאזהרות לגבי הנתיבים ב-openapi.json שלא דורשים מפתח API. בסיום מוצלח, מוצגת שורה שדומה לשורה הבאה עם מזהה הגדרות השירות ושם השירות:

Service Configuration [2017-02-13-r2] uploaded for service [example-project-12345.appspot.com]

בדוגמה הקודמת, 2017-02-13-r2 הוא מזהה הגדרות השירות ו-example-project-12345.appspot.com הוא שם השירות.

מידע נוסף זמין במאמר gcloud פריסת שירותים של Endpoints.

בדיקת השירותים הנדרשים

כדי לספק ניהול API, ‏ Endpoints Frameworks דורש את השירותים הבאים:
שם כותרת
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API

ברוב המקרים, הפקודה gcloud endpoints services deploy מפעילה את השירותים הנדרשים האלה. עם זאת, הפקודה gcloud מסתיימת בהצלחה אבל לא מפעילה את השירותים הנדרשים בנסיבות הבאות:

  • אם השתמשתם באפליקציה של צד שלישי כמו Terraform ולא כללתם את השירותים האלה.

  • הפריסה של הגדרת ה-Endpoints בוצעה בפרויקטGoogle Cloud קיים שבו השירותים האלה הושבתו באופן מפורש.

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

gcloud services list

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

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

צריך גם להפעיל את שירות Endpoints:

gcloud services enable ENDPOINTS_SERVICE_NAME

כדי לדעת מהו ENDPOINTS_SERVICE_NAME, אפשר:

  • אחרי פריסת ההגדרה של Endpoints, נכנסים לדף Endpoints במסוף Cloud. רשימת האפשרויות האפשריות של ENDPOINTS_SERVICE_NAME מוצגת בעמודה שם השירות.

  • ב-OpenAPI, ‏ ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדה host במפרט OpenAPI. ב-gRPC, ‏ ENDPOINTS_SERVICE_NAME הוא הערך שציינתם בשדה name בהגדרות של נקודות הקצה של gRPC.

מידע נוסף על פקודות gcloud זמין במאמר שירותי gcloud.

הרצת הדוגמה באופן מקומי

אחרי שפורסים את הגדרת Endpoints, אפשר להריץ את הדוגמה באופן מקומי.

  1. יוצרים משתנה סביבה בשם ENDPOINTS_SERVICE_NAME, שמשמש בקובץ appengine-web.xml של הדוגמה להגדרת שם המארח. בדוגמה הבאה, מחליפים את YOUR_PROJECT_ID במזהה הפרויקט ב-Google Cloud .

    ב-Linux או ב-Mac OS:

    export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com

    ב-Windows PowerShell:

    $Env:ENDPOINTS_SERVICE_NAME="YOUR_PROJECT_ID.appspot.com"

  2. מקבלים פרטי כניסה חדשים של משתמש לשימוש ב-Application Default Credentials:

    gcloud auth application-default login

  3. מריצים את שרת הפיתוח:

    mvn appengine:run

    אפשר להגיע למופע המקומי בכתובת http://localhost:8080, כפי שמצוין ביומנים שהודפסו על ידי הפקודה mvn appengine:run:

    [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/

  4. שליחת בקשה למופע המקומי:

‫Linux או Mac OS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

במהלך curl הקודמים:

  • האפשרות --data מציינת את הנתונים שיישלחו ל-API.
  • האפשרות --header מציינת שהנתונים הם בפורמט JSON.

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

בדוגמה הקודמת, שתי השורות הראשונות מסתיימות בגרש הפוך. כשמדביקים את הדוגמה ב-PowerShell, צריך לוודא שאין רווח אחרי התווים '`'. מידע על האפשרויות שבהן נעשה שימוש בבקשת הדוגמה מופיע במאמר Invoke-WebRequest במסמכי התיעוד של מיקרוסופט.

ה-API מחזיר את ההודעה ששלחתם לו, ומגיב עם:

{
 "message": "hello world"
}

פריסת ה-API backend

עד עכשיו פרסתם את הגדרת OpenAPI ב-Service Management, אבל עדיין לא פרסתם את הקוד שמשרת את העורף של ה-API. בקטע הזה מוסבר איך פורסים את ה-API לדוגמה ב-App Engine.

כדי לפרוס את העורף של ה-API:

  1. מוודאים שאתם נמצאים בספרייה java-docs-samples/appengine-java8/endpoints-v2-backend.

  2. פורסים את קוד ההטמעה של ה-API באמצעות Maven:

     mvn appengine:deploy

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

  3. מחכים שההעלאה תסתיים.

    מומלץ להמתין כמה דקות לפני שליחת בקשות ל-API בזמן שהאפליקציה עוברת אתחול מלא ב-App Engine.

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

אחרי שמפעילים את ה-API ואת קובץ ההגדרות שלו, אפשר לשלוח בקשות ל-API.

‫Linux או Mac OS

שליחת בקשת HTTP באמצעות curl. מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב-Google Cloud :

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

במהלך curl הקודמים:

  • האפשרות --data מציינת את הנתונים שיישלחו ל-API.
  • האפשרות --header מציינת שהנתונים הם בפורמט JSON.

PowerShell

שליחת בקשת HTTP באמצעות Invoke-WebRequest. מחליפים את [YOUR_PROJECT_ID] במזהה הפרויקט ב- Google Cloud :

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content

בדוגמה הקודמת, שתי השורות הראשונות מסתיימות בגרש הפוך. כשמדביקים את הדוגמה ב-PowerShell, צריך לוודא שאין רווח אחרי התווים '`'. מידע על האפשרויות שבהן נעשה שימוש בבקשת הדוגמה מופיע במאמר Invoke-WebRequest במסמכי התיעוד של מיקרוסופט.

אפליקציה של צד שלישי

אפשר להשתמש באפליקציה של צד שלישי, כמו התוסף Postman לדפדפן Chrome, כדי לשלוח את הבקשה:

  • בוחרים באפשרות POST כפועל ה-HTTP.
  • בכותרת, בוחרים את המפתח content-type ואת הערך application/json.
  • בגוף ההודעה, מזינים את הפרטים הבאים:
    {"message":"hello world"}
  • מזינים את כתובת ה-URL של האפליקציה לדוגמה. לדוגמה:
    https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

ה-API מחזיר את ההודעה ששלחתם לו, ומגיב עם:

{
 "message": "hello world"
}

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

הרגע פרסתם ובדקתם API ב-Endpoints Frameworks!

מעקב אחר פעילות ב-API

  1. אפשר לראות את הגרפים של הפעילות ב-API במסוף Google Cloud בדף Endpoints > Service.

    לדף Endpoints Services

    יכול להיות שיחלפו כמה רגעים עד שהבקשה תשתקף בתרשימים.

  2. מעיינים ביומני הבקשות של ה-API בדף Logs Explorer.

    כניסה לדף Logs Explorer

יצירת פורטל למפתחים עבור ה-API

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

הסרת המשאבים

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

  1. במסוף Google Cloud , נכנסים לדף Manage resources.

    כניסה לדף Manage resources

  2. ברשימת הפרויקטים, בוחרים את הפרויקט שרוצים למחוק ולוחצים על Delete.
  3. כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.

המאמרים הבאים