Menyiapkan lingkungan pengembangan

Halaman ini menjelaskan cara menyiapkan lingkungan pengembangan untuk membangun dan men-deploy backend API menggunakan Cloud Endpoints Frameworks untuk lingkungan standar App Engine. Halaman ini menggunakan contoh kode kerangka kerja Endpoints Frameworks versi 2.0 untuk menjelaskan software dan komponen dasar yang Anda butuhkan untuk memulai.

Anda dapat menggunakan endpoints-skeleton-archetype atau hello-endpoints-archetype yang dijelaskan dalam Menggunakan Apache Maven dan plugin App Engine (berbasis Google Cloud CLI) untuk membuat project Endpoints Frameworks versi 2.0 baru.

Untuk lebih memahami langkah-langkah yang diperlukan untuk men-deploy API sampel menggunakan Framework Endpoint, lihat tutorial Memulai Framework Endpoint di App Engine.

Sebelum memulai

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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.

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.

1. Catat ID project Google Cloud karena akan diperlukan nanti.

Menginstal dan mengonfigurasi software yang diperlukan

1. Jika Anda belum menginstal Java 8, download Java Development Kit (JDK) dari situs Oracle, lalu instal.
2. Instal Maven atau Gradle:

   Maven

   1. Download Apache Maven versi 3.3.9 atau yang lebih baru
   2. Instal dan konfigurasi Maven untuk lingkungan pengembangan lokal Anda.

   Gradle

   • Instal Gradle.
3. Download dan inisialisasi Google Cloud CLI.
4. Jalankan perintah berikut:
   1. Pastikan gcloud CLI diberi otorisasi untuk mengakses data dan layanan Anda di Google Cloud:

      gcloud auth login

   2. Menggunakan kredensial default aplikasi:

      gcloud auth application-default login

   3. Instal komponen app-engine-java Google Cloud SDK:

      gcloud components install app-engine-java

   4. Update ke versi terbaru Google Cloud SDK dan semua komponen:

      gcloud components update

5. Buat aplikasi App Engine:
   1. Tetapkan project default ke Google Cloud project ID Anda:

      gcloud config set project YOUR_PROJECT_ID

      Ganti YOUR_PROJECT_ID dengan ID project Google Cloud Anda. Jika Anda memiliki project Google Cloud lain, dan Anda ingin menggunakan gcloud untuk mengelolanya, lihat Mengelola konfigurasi gcloud CLI.

   2. Pilih region tempat Anda ingin membuat aplikasi App Engine. Lihat Lokasi App Engine untuk mengetahui daftar region.
   3. Buat aplikasi App Engine. Ganti YOUR_PROJECT_ID dengan ID Google Cloud project Anda dan YOUR_REGION dengan region tempat Anda ingin membuat aplikasi App Engine.

        gcloud app create \
        --project=YOUR_PROJECT_ID \
        --region=YOUR_REGION

Mendapatkan contoh kerangka Endpoints Frameworks

Contoh kerangka Endpoints Frameworks versi 2.0 berisi skrip build yang diperlukan untuk Maven dan Gradle. Direktori ini juga berisi file yang diperlukan untuk mulai membuat API pertama Anda.

1. Clone repositori contoh ke komputer lokal Anda:

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

2. Ubah ke direktori yang berisi contoh kerangka Endpoints Frameworks:

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

   Contoh memiliki struktur direktori berikut:

   

   • MyApi.java berisi class kosong yang dapat Anda gunakan untuk mulai menulis API. Lihat contoh echo untuk contoh kode yang akan membantu Anda memulai.

   • web.xml adalah file standar yang digunakan untuk mengonfigurasi servlet.

   • appengine-web.xml menentukan informasi yang diperlukan untuk men-deploy API ke lingkungan standar App Engine menggunakan Java 8.

   • pom.xml berisi informasi project dan konfigurasi yang digunakan oleh Maven untuk membuat project dan men-deploy API ke App Engine.

   • build.gradle berisi informasi project dan konfigurasi yang digunakan oleh Gradle untuk membangun project dan men-deploy API ke App Engine.

Mengonfigurasi file build

Bagian ini menjelaskan file Maven pom.xml dan Gradle build.gradle yang disertakan dalam contoh kode. Selain memasukkan ID project Google Cloud agar dapat digunakan di nama host, file build siap digunakan untuk mulai membuat API.

Tentang konfigurasi minimum

Bagian ini menjelaskan konfigurasi minimum yang diperlukan dalam file build Anda.

Maven

Dependensi minimum

Berikut adalah dependensi minimum yang diperlukan di pom.xml untuk memulai:

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

• Dependensi endpoints-framework berisi class yang diperlukan untuk membuat API Anda.
• Anda memerlukan App Engine Standard API SDK (appengine-api-sdk) untuk men-deploy project ke lingkungan standar App Engine.
• Paket javax.servlet standar diperlukan untuk membuat servlet.
• Paket javax.inject standar diperlukan untuk mendukung injeksi dependensi.

Menerapkan plugin

Plugin berikut diterapkan untuk mengaktifkannya:

<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 memperluas plugin java untuk menambahkan dukungan untuk merakit aplikasi web.
• appengine-maven-plugin diperlukan untuk menjalankan API di App Engine.
• endpoints-framework-maven-plugin menyediakan tugas dan konfigurasi untuk membuat project Endpoints Frameworks.

Gradle

Dependensi plugin

Berikut menunjukkan plugin yang diperlukan untuk membangun API Anda:

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'
  }
}

• Plugin Gradle Endpoints Frameworks digunakan untuk membuat dokumen OpenAPI dan membuat library klien.
• Anda memerlukan plugin Gradle App Engine untuk men-deploy project ke App Engine.

Menerapkan plugin

Plugin berikut diterapkan untuk mengaktifkannya di skrip build Gradle Anda:

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

• Plugin java menambahkan langkah-langkah kompilasi dan build khusus Java ke project Anda.
• Plugin war memperluas plugin java untuk menambahkan dukungan untuk merakit aplikasi web.
• Plugin endpoints-framework-server menyediakan dukungan sisi server untuk plugin Gradle Endpoints Frameworks.
• Plugin appengine diperlukan untuk menjalankan API di App Engine.

Dependensi project

Project menggunakan dependensi berikut:

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'
}

• Dependensi endpoints-framework berisi class yang diperlukan untuk membuat API Anda.
• App Engine Standard API SDK (appengine-api-sdk) diperlukan untuk men-deploy project Anda ke lingkungan standar App Engine.
• Paket javax.servlet standar diperlukan untuk membuat servlet .
• Paket javax.inject standar diperlukan untuk mendukung injeksi dependensi.

Menentukan nama host untuk layanan Anda

Framework Endpoints menggunakan nama yang kompatibel dengan DNS untuk mengidentifikasi layanan secara unik. Karena Google Cloud project ID dijamin unik secara global, Anda harus menggunakan project ID Google Cloud sebagai bagian dari nama layanan API Anda.

Anda harus menambahkan project ID Google Cloud ke file build untuk mengonfigurasi nama host untuk layanan Anda. Nama host harus dalam format berikut:

YOUR_PROJECT_ID.appspot.com

Saat Anda men-deploy API ke App Engine, entri DNS dengan nama dalam format YOUR_PROJECT_ID.appspot.com akan dibuat secara otomatis. Nama host adalah nama layanan Cloud Endpoints dan nama domain yang Anda gunakan untuk mengirim permintaan ke API Anda.

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>

Di kolom hostname, ganti YOUR_PROJECT_ID dengan ID project Google Cloud Anda.

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"
}

Tetapkan variabel projectID ke project ID Google Cloud Anda. Contoh: def projectId = 'example-project-12345'

Mengonfigurasi servlet Endpoints

Servlet Endpoints menangani permintaan masuk dan meneruskannya ke layanan backend yang berjalan di App Engine. Servlet Endpoints diperlukan agar API Anda dikelola oleh Endpoints.

Untuk mengetahui informasi selengkapnya tentang web.xml, lihat Deployment descriptor: 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>

Mengonfigurasi deployment App Engine

File appengine-web.xml digunakan untuk menentukan konfigurasi lingkungan standar App Engine saat API di-deploy. Lihat referensi appengine-web.xml untuk mengetahui informasi selengkapnya.

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

Langkah berikutnya

• Tulis dan beri anotasi pada kode API backend Anda.
• Pelajari anotasi lebih lanjut.
• Tambahkan pengelolaan API.
• Deploy dan uji API Anda.
• Pelajari lebih lanjut jenis parameter dan nilai yang didukung.