הגדרת סביבת פיתוח

בדף הזה מוסבר איך להגדיר את סביבת הפיתוח כדי ליצור ולפרוס את ה-API של ה-Backend באמצעות Cloud Endpoints Frameworks בסביבה הרגילה של App Engine. בדף הזה נעשה שימוש בדוגמת קוד של Endpoints Frameworks version 2.0 skeleton כדי להסביר את התוכנה והרכיבים הבסיסיים שצריך כדי להתחיל.

אפשר להשתמש ב-endpoints-skeleton-archetype או ב-hello-endpoints-archetype שמתוארים במאמר שימוש ב-Apache Maven ובתוסף App Engine (מבוסס Google Cloud CLI) כדי ליצור פרויקט חדש של Endpoints Frameworks גרסה 2.0.

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

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

  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. חשוב לרשום את Google Cloud מזהה הפרויקט כי תצטרכו אותו בהמשך.

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

  1. אם Java 8 לא מותקן, מורידים את Java Development Kit ‏ (JDK) מ האתר של Oracle ומתקינים אותו.
  2. מתקינים את Maven או את Gradle:

    Maven

    1. הורדת Apache Maven בגרסה 3.3.9 ואילך
    2. מתקינים ומגדירים את Maven בסביבת הפיתוח המקומית.

    Gradle

  3. מורידים ומפעילים את Google Cloud CLI.
  4. מריצים את הפקודות הבאות:
    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
  5. יוצרים אפליקציית App Engine:
    1. מגדירים את פרויקט ברירת המחדל למזהה הפרויקט שלכם: Google Cloud 
      gcloud config set project YOUR_PROJECT_ID

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

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

קבלת דוגמה לשלד של Endpoints Frameworks

הדוגמה של שלד גרסה 2.0 של Endpoints Frameworks מכילה את סקריפטים ה-build הדרושים ל-Maven ול-Gradle. הוא גם מכיל את הקבצים הנדרשים כדי להתחיל ליצור את ה-API הראשון.

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

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

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

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

    לדוגמה יש את מבנה הספריות הבא:

    דוגמה לפריסה של שלד של Endpoints Frameworks

    • ‫MyApi.java מכיל מחלקה ריקה שאפשר להשתמש בה כדי להתחיל לכתוב את ה-API. כדי להתחיל, אפשר להיעזר בקוד לדוגמה שמופיע בדוגמה של echo.

    • ‫web.xml הוא קובץ סטנדרטי שמשמש להגדרת servlet.

    • ‫appengine-web.xml מגדיר מידע שנדרש לפריסת ה-API בסביבה הרגילה של App Engine באמצעות Java 8.

    • ‫pom.xml כולל מידע על הפרויקט וההגדרות שמשמש את Maven כדי לבנות את הפרויקט ולפרוס את ה-API ב-App Engine.

    • ‫build.gradle כולל מידע על הפרויקט וההגדרות שמשמש את Gradle כדי לבנות את הפרויקט ולפרוס את ה-API ב-App Engine.

הגדרת קובצי ה-build

בקטע הזה מתוארים קובצי Maven‏ pom.xml ו-Gradle‏ build.gradle שכלולים בקוד לדוגמה. חוץ מהזנת מזהה הפרויקט Google Cloud כדי שאפשר יהיה להשתמש בו בשם המארח, קובצי ה-build מוכנים להתחלת יצירת ה-API.

מידע על ההגדרה המינימלית

בקטע הזה מוסבר על ההגדרה המינימלית שנדרשת בקובץ ה-build.

Maven

תלות מינימלית

אלה התלויות המינימליות שנדרשות ב-pom.xml כדי להתחיל:

<dependencies>
  <!-- Compile/runtime dependencies -->
  <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.2</version>
  </dependency>
  <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>2.0.23</version>
  </dependency>
  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <type>jar</type>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>javax.inject</groupId>
    <artifactId>javax.inject</artifactId>
    <version>1</version>
  </dependency>
</dependencies>

  • התלות endpoints-framework מכילה את המחלקות הדרושות ליצירת ה-API.
  • כדי לפרוס את הפרויקט בסביבה הסטנדרטית של App Engine, צריך את App Engine Standard API SDK ‏ (appengine-api-sdk).
  • כדי ליצור servlet, צריך את חבילת javax.servlet הרגילה.
  • חבילת javax.inject הסטנדרטית נדרשת כדי לתמוך ב הזרקת תלות.

החלת פלאגינים

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

<build>
  <!-- for hot reload of the web application-->
  <outputDirectory>${project.build.directory}/${project.build.finalName}/WEB-INF/classes</outputDirectory>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <version>3.4.0</version>
      <configuration>
        <webResources>
          <resources>
            <directory>${basedir}/src/main/webapp/WEB-INF</directory>
            <filtering>true</filtering>
            <targetPath>WEB-INF</targetPath>
          </resources>
        </webResources>
      </configuration>
    </plugin>
    <plugin>
      <groupId>com.google.cloud.tools</groupId>
      <artifactId>appengine-maven-plugin</artifactId>
      <version>2.5.0</version>
      <configuration>
        <!-- deploy configuration -->
        <projectId>GCLOUD_CONFIG</projectId>
        <version>GCLOUD_CONFIG</version>
      </configuration>
    </plugin>
    <plugin>
      <groupId>com.google.cloud.tools</groupId>
      <artifactId>endpoints-framework-maven-plugin</artifactId>
      <version>2.1.0</version>
      <configuration>
        <!-- plugin configuration -->
        <!--
        You must replace YOUR_PROJECT_ID with your
        Google Cloud Project Id
      -->
        <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
      </configuration>
    </plugin>
  </plugins>
</build>
  • הפלאגין maven-war-plugin מרחיב את הפלאגין java כדי להוסיף תמיכה בהרכבת אפליקציית אינטרנט.
  • ה- appengine-maven-plugin נדרש כדי להריץ את ה-API ב-App Engine.
  • ‫ endpoints-framework-maven-plugin מספק משימות והגדרות ליצירת פרויקטים של Endpoints Frameworks.

Gradle

יחסי תלות של פלאגינים

בהמשך מוצגים הפלאגינים שנדרשים כדי ליצור את ה-API:

buildscript {
  repositories {
    mavenCentral()
  }

  dependencies {
    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:2.1.0'
    classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.5.0'
  }
}

החלת פלאגינים

התוספים הבאים מוחלים כדי להפעיל אותם בסקריפט ה-build של Gradle:

apply plugin: 'java'
apply plugin: 'war'
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
apply plugin: 'com.google.cloud.tools.appengine'

  • הפלאגין java מוסיף לפרויקט שלכם שלבים ספציפיים של קומפילציה ובנייה ב-Java.
  • הפלאגין war מרחיב את הפלאגין java כדי להוסיף תמיכה בהרכבת אפליקציית אינטרנט.
  • הפלאגין endpoints-framework-server מספק תמיכה בצד השרת לפלאגין Endpoints Frameworks Gradle.
  • כדי להריץ את ה-API ב-App Engine, צריך את הפלאגין appengine.

תלות של הפרויקט במשאבים

הפרויקט משתמש בתלות הבאה:

dependencies {
    compile 'com.google.endpoints:endpoints-framework:2.2.2'
    compile 'com.google.appengine:appengine-api-1.0-sdk:2.0.23'

    compile 'javax.inject:javax.inject:1'
    compileOnly 'javax.servlet:javax.servlet-api:3.1.0'
}

  • התלות endpoints-framework מכילה את המחלקות הדרושות ליצירת ה-API.
  • נדרש App Engine Standard API SDK‏ (appengine-api-sdk) כדי לפרוס את הפרויקט בסביבה הסטנדרטית של App Engine.
  • כדי ליצור servlet, צריך את חבילת javax.servlet הרגילה.
  • חבילת javax.inject הסטנדרטית נדרשת כדי לתמוך ב הזרקת תלות.

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

‫Endpoints Frameworks משתמש בשמות שתואמים ל-DNS כדי לזהות שירותים באופן ייחודי. מזהי פרויקטים הם ייחודיים באופן גלובלי, ולכן מומלץ להשתמש במזהה הפרויקט כחלק משם השירות של ה-API. Google Cloud Google Cloud

כדי להגדיר את שם המארח של השירות, צריך להוסיף את מזהה הפרויקט לקובצי ה-build. Google Cloud שם המארח צריך להיות בפורמט הבא:

YOUR_PROJECT_ID.appspot.com

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

Maven

<plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>endpoints-framework-maven-plugin</artifactId>
  <version>2.1.0</version>
  <configuration>
    <!-- plugin configuration -->
    <!--
    You must replace YOUR_PROJECT_ID with your
    Google Cloud Project Id
  -->
    <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
  </configuration>
</plugin>

בשדה hostname, מחליפים את YOUR_PROJECT_ID במזהה הפרויקט Google Cloud .

Gradle

// You must replace YOUR_PROJECT_ID with your Google Cloud Project Id
def projectId = 'YOUR_PROJECT_ID'

endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "${projectId}.appspot.com"
}

מגדירים את המשתנה projectID למזהה הפרויקט ב- Google Cloud. לדוגמה: def projectId = 'example-project-12345'

הגדרת ה-servlet של Endpoints

רכיב ה-servlet של Endpoints מטפל בבקשות נכנסות ומעביר אותן לשירות הקצה העורפי שפועל ב-App Engine. ה-servlet של Endpoints נדרש כדי שממשק ה-API שלכם ינוהל על ידי Endpoints.

מידע נוסף על web.xml זמין במאמר בנושא קובץ תיאור הפריסה: web.xml.

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <!-- Wrap the backend with Endpoints Frameworks v2. -->
    <servlet>
        <servlet-name>EndpointsServlet</servlet-name>
        <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
        <init-param>
            <param-name>services</param-name>
            <param-value>com.example.skeleton.MyApi</param-value>
        </init-param>
    </servlet>
    <!-- Route API method requests to the backend. -->
    <servlet-mapping>
        <servlet-name>EndpointsServlet</servlet-name>
        <url-pattern>/_ah/api/*</url-pattern>
    </servlet-mapping>
</web-app>

הגדרת הפריסה של App Engine

קובץ appengine-web.xml משמש להגדרת התצורה של סביבת App Engine Standard כשפורסים את ה-API. מידע נוסף זמין במאמר בנושא appengine-web.xml.

<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <runtime>java8</runtime>
    <threadsafe>true</threadsafe>

    <system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
    </system-properties>
</appengine-web-app>

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