Menyiapkan lingkungan pengembangan

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

Sebaiknya gunakan 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 mendapatkan pemahaman yang lebih baik tentang langkah-langkah yang diperlukan untuk men-deploy API contoh menggunakan Framework Endpoint, lihat tutorial Memulai Framework Endpoint di App Engine.

Sebelum memulai

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

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

   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

3. Make sure 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.

   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

5. Make sure that billing is enabled for your Google Cloud project.

6. Catat project ID Google Cloud karena Anda akan memerlukannya 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 lakukan 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 project ID Google Cloud Anda:

      gcloud config set project YOUR_PROJECT_ID

      Ganti YOUR_PROJECT_ID dengan project ID Google Cloud Anda. Jika Anda memiliki project Google Cloud lain, dan 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 project ID Google Cloud 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. File 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 Framework:

    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 mengetahui contoh kode yang dapat 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 mem-build project dan men-deploy API ke App Engine.

   • build.gradle berisi informasi project dan konfigurasi yang digunakan oleh Gradle untuk mem-build 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 kode contoh. Selain memasukkan ID project Google Cloud Anda agar dapat digunakan di nama host, file build siap untuk Anda gunakan untuk mulai membuat API.

Tentang konfigurasi minimum

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

Maven

Dependensi minimum

Berikut ini menunjukkan 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 mem-build 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 menyusun aplikasi web.
• appengine-maven-plugin diperlukan untuk menjalankan API di App Engine.
• endpoints-framework-maven-plugin menyediakan tugas dan konfigurasi untuk mem-build project Endpoints Frameworks.

Gradle

Dependensi plugin

Berikut adalah plugin yang diperlukan untuk mem-build 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 dalam 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 menyusun aplikasi web.
• Plugin endpoints-framework-server menyediakan dukungan sisi server ke plugin Gradle Endpoints Frameworks.
• Plugin appengine diperlukan untuk menjalankan API di App Engine.

Dependensi project

Dependensi berikut digunakan oleh project:

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 mem-build servlet.
• Paket javax.inject standar diperlukan untuk mendukung injeksi dependensi.

Menentukan nama host untuk layanan Anda

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

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.

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 Endpoint

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

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

• Tulis dan anotasikan kode API backend Anda.
• Pelajari anotasi lebih lanjut.
• Tambahkan pengelolaan API.
• Men-deploy dan menguji API.
• Pelajari lebih lanjut parameter dan jenis nilai yang didukung.