Bermigrasi ke Cloud Endpoints Frameworks versi 2.0 untuk App Engine

Halaman ini menjelaskan proses migrasi aplikasi Cloud Endpoints versi 1.0 yang ada ke Framework Endpoint untuk App Engine di Java.

Manfaat

Framework baru ini menghadirkan sejumlah manfaat, termasuk:

Mengurangi latensi permintaan.
Integrasi yang lebih baik dengan fitur App Engine, seperti domain kustom.
Dukungan resmi untuk konfigurasi Guice.
Secara opsional, fitur pengelolaan API baru.

Framework Endpoint versi 2.0 tidak memengaruhi antarmuka ke API Anda. Klien yang sudah ada akan terus berfungsi setelah migrasi tanpa perubahan kode sisi klien apa pun.

Fitur dan alat yang saat ini dikecualikan

Fitur berikut saat ini tidak tersedia. Jika Anda memerlukan salah satu dari hal tersebut, kirimkan permintaan fitur.

Protokol JSON-RPC, yang diperlukan untuk klien iOS lama. Untuk membuat klien iOS untuk Endpoints Frameworks API 2.0, sebaiknya gunakan library klien Objective-C Google API untuk REST API.
ETag otomatis
Kolom jenis otomatis
Integrasi IDE
fields respons sebagian
Pembuatan metode PATCH API otomatis

Selain itu, dukungan Android Studio untuk Endpoint versi 1.0 saat ini tidak didukung untuk versi 2.0.

Bermigrasi ke Endpoints Frameworks versi 2.0

Endpoints Frameworks versi 2.0 telah dipindahkan ke artefak Maven dalam grup com.google.endpoints. Dasar yang diperlukan JAR ada di artefak endpoints-framework. Jika Anda ingin menggunakan konfigurasi Guice, tambahkan artefak endpoints-framework-guice.

Petunjuk berikut memberikan contoh cara bermigrasi dari Endpoint Frameworks versi 1.0 ke Endpoints Frameworks versi 2.0 menggunakan Dokumen Discovery:

Download dan lakukan inisialisasi Google Cloud CLI.
Jalankan perintah berikut:
1. Pastikan bahwa gcloud CLI diberi otorisasi untuk mengakses data dan layanan Anda di Google Cloud:
```
gcloud auth login
```
2. Gunakan 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
```

Bermigrasi menggunakan Maven atau Gradle

Maven

Hapus dependensi lama, yang merupakan artefak appengine-endpoints:

<dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>

Tambahkan dependensi Endpoints Frameworks baru:

<dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.1</version>
</dependency>

Tambahkan plugin Endpoints Frameworks baru dan tentukan nama host untuk dokumen penemuan yang dihasilkan:

<plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>endpoints-framework-maven-plugin</artifactId>
    <version>1.0.2</version>
    <configuration>
        <!-- plugin configuration -->
        <hostname>YOUR-PROJECT-ID.appspot.com</hostname>
    </configuration>
</plugin>

Tambahkan plugin App Engine Maven baru:

<plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>appengine-maven-plugin</artifactId>
    <version>1.3.2</version>
    <configuration>
        <!-- deploy configuration -->
    </configuration>
</plugin>

Catatan: Plugin App Engine Maven lama, dengan grup com.google.appengine, tidak kompatibel dengan plugin Endpoints Frameworks. Anda harus menggunakan versi baru.

Update titik entri API di file web.xml project Anda:

Ganti nama semua kemunculan SystemServiceServlet menjadi EndpointsServlet
Ganti semua kemunculan jalur /_ah/spi/ ke jalur wajib baru /_ah/api/

Kode berikut menunjukkan konten web.xml sebelum dan sesudah migrasi:

Sebelum migrasi

Framework Endpoints versi 1.0 web.xml:

<servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

Setelah migrasi

Framework Endpoints versi 2.0 web.xml:

<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.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

Setelah memodifikasi dependensi, bersihkan projec:
```
mvn clean
```
Anda dapat membuat dokumen discovery:
```
mvn endpoints-framework:discoveryDocs
```
Pelajari lebih lanjut sasaran plugin Framework Maven Endpoints.
Anda dapat men-deploy project:
```
mvn appengine:deploy
```
Pelajari lebih lanjut sasaran plugin Maven App Engine.

Catatan: Saat bermigrasi, Anda harus men-deploy ke versi App Engine baru. Hal ini dilakukan secara otomatis jika Anda tidak menentukan versi. Lihat Masalah umum.

Gradle

Hapus dependensi lama, yang merupakan artefak appengine-endpoints:

compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

Tambahkan dependensi Endpoints Frameworks baru:

compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'

Tambahkan plugin App Engine dan Endpoints Framework baru:

buildscript {    // Configuration for building
  repositories {
    mavenCentral()
    jcenter()    // Bintray's repository - a fast Maven Central mirror & more
  }
  dependencies {
    // App Engine Gradle plugin
    classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.3.3'

    // Endpoints Frameworks Gradle plugin
    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
  }
}

Terapkan plugin App Engine dan Endpoints Frameworks baru:

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

Tentukan endpoint nama host untuk dokumen penemuan yang dibuat:

endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "YOUR-PROJECT-ID.appspot.com"
}

Update titik entri API di file web.xml project Anda:

Ganti nama semua kemunculan SystemServiceServlet menjadi EndpointsServlet
Ganti semua kemunculan jalur /_ah/spi/ ke jalur wajib baru /_ah/api/

Kode berikut menunjukkan konten web.xml sebelum dan sesudah migrasi:

Sebelum migrasi

Framework Endpoints versi 1.0 web.xml:

<servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

Setelah migrasi

Framework Endpoints versi 2.0 web.xml:

<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.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

Setelah memodifikasi dependensi, bersihkan project menggunakan:
```
gradle clean
```
Anda dapat membuat dokumen discovery menggunakan:
```
gradle endpointsDiscoveryDocs
```
Pelajari tugas plugin Gradle Endpoints Frameworks lebih lanjut
Anda dapat men-deploy project menggunakan:
```
gradle appengineDeploy
```
Pelajari lebih lanjut tugas plugin Gradle App Engine.

Catatan: Saat bermigrasi, Anda harus men-deploy ke versi App Engine baru. Hal ini dilakukan secara otomatis jika Anda tidak menentukan versi. Lihat Masalah umum.

Menggunakan Guice untuk mengonfigurasi Framework Endpoint untuk Java

Jika Anda ingin menggunakan Guice:

Tambahkan dependensi Endpoints Frameworks Guice baru:

Maven

<dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework-guice</artifactId>
    <version>2.2.1</version>
</dependency>

Gradle

compile 'com.google.endpoints:endpoints-framework-guice:2.0.9'

Deklarasikan modul baru yang memperluas EndpointsModule, dan konfigurasikan, seperti berikut:

public class EchoEndpointModule extends EndpointsModule {
  @Override
  public void configureServlets() {
    super.configureServlets();

    bind(ServiceManagementConfigFilter.class).in(Singleton.class);
    filter("/_ah/api/*").through(ServiceManagementConfigFilter.class);

    Map<String, String> apiController = new HashMap<String, String>();
    apiController.put("endpoints.projectId", "YOUR-PROJECT-ID");
    apiController.put("endpoints.serviceName", "YOUR-PROJECT-ID.appspot.com");

    bind(GoogleAppEngineControlFilter.class).in(Singleton.class);
    filter("/_ah/api/*").through(GoogleAppEngineControlFilter.class, apiController);

    bind(Echo.class).toInstance(new Echo());
    configureEndpoints("/_ah/api/*", ImmutableList.of(Echo.class));
  }
}

Memverifikasi deployment baru

Anda dapat memverifikasi bahwa framework baru menyalurkan traffic:

Kirim beberapa permintaan ke deployment baru.
Di konsol Google Cloud, buka halaman Logging > Logs Explorer.

Buka halaman Logs Explorer
Jika permintaan ditampilkan dengan jalur yang dimulai dengan /_ah/api, berarti Framework Endpoint versi 2.0 sekarang menyalurkan API Anda. Log tidak boleh menampilkan permintaan apa pun dengan jalur yang diawali dengan /_ah/spi. Permintaan ini menunjukkan bahwa proxy Endpoints Frameworks versi 1.0 masih menayangkan permintaan.

Menambahkan pengelolaan Endpoints API

Framework Endpoints versi 2.0 juga memungkinkan Anda mengaktifkan fitur pengelolaan API, termasuk:

Pengelolaan kunci API
Berbagi API
Autentikasi pengguna
Metrik API
Log API

Untuk mulai menggunakan fitur ini, lihat Menambahkan pengelolaan API.

Pemecahan masalah

Bagian ini menjelaskan perilaku tidak menentu umum saat bermigrasi ke Framework Endpoint versi 2.0 dan solusi yang disarankan.

API menampilkan `404` error, tetapi API Explorer tetap mencantumkan API dengan benar

Anda harus menghapus konfigurasi Endpoints Frameworks versi 1.0 lama saat bermigrasi ke Endpoints Frameworks versi 2.0. Jika konfigurasi lama masih ada di konfigurasi aplikasi, layanan Endpoint akan terus memperlakukan aplikasi sebagai aplikasi versi 1.0. Anda mungkin melihat permintaan di log App Engine dikirim ke /_ah/spi, sehingga mengakibatkan error HTTP 404 yang dikirim ke klien.

Hapus baris berikut dari file web.xml Anda, jika ada:

<servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>...</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

Pastikan file web.xml Anda berisi hal berikut:

<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

API menampilkan error refleksi

Anda hanya boleh memaketkan artefak endpoints-framework ke dalam aplikasi Anda, bukan JAR appengine-endpoints lama. Jika men-deploy aplikasi dengan kedua JAR, Anda mungkin akan mengalami error refleksi atau error jenis runtime, seperti NoClassDefFoundError, NoSuchMethodError, dan ClassCastException. Hapus baris berikut dari file build Anda, jika ada:

Maven

<dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>

Gradle

compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'

Selain itu, jika salah satu dependensi Anda lainnya bergantung pada versi Guava yang lebih lama, hal ini juga dapat berwujud sebagai metode TypeToken yang tidak ada. Anda harus memastikan bahwa Anda menggunakan Guava v19 atau menggunakan artefak endpoints-framework-all, yang membayangi dependensi.

Sumber library klien tidak dikompilasi

Jika Anda melihat error seperti method does not override or implement a method from a supertype, atau cannot find symbol method setBatchPath(String), berarti aplikasi klien Anda kemungkinan bergantung pada library klien Google Java versi lama. Anda harus memastikan bahwa artefak google-api-client Anda adalah 1.23.0 atau yang lebih tinggi.

Maven

<dependency>
    <groupId>com.google.api-client</groupId>
    <artifactId>google-api-client</artifactId>
    <version>1.23.0</version>
</dependency>

Gradle

compile group: 'com.google.api-client', name: 'google-api-client', version: '1.23.0'

Masalah terkait peningkatan JPA/JDO Datanucleus

Maven

Plugin Maven App Engine berbasis Google Cloud CLI yang baru tidak mendukung peningkatan jenis apa pun dari Datanucleus. Jika project Anda menggunakan dukungan peningkatan Datanucleus JDO atau JPA dari plugin lama, Anda harus mengonfigurasi plugin Maven Datanucleus pihak ketiga secara terpisah saat melakukan migrasi. Lihat informasi selengkapnya di sini:

Gradle

Jika project Anda menggunakan peningkatan Datanucleus JPA/JDO gradle-appengine-plugin, Anda harus mengonfigurasi peningkatan Datanucleus secara manual setelah beralih ke plugin Gradle berbasis gcloud CLI yang baru. Lihat contoh dari Stackoverflow.

Bermigrasi ke Cloud Endpoints Frameworks versi 2.0 untuk App Engine

Manfaat

Fitur dan alat yang saat ini dikecualikan

Bermigrasi ke Endpoints Frameworks versi 2.0

Bermigrasi menggunakan Maven atau Gradle

Maven

Sebelum migrasi

Setelah migrasi

Gradle

Sebelum migrasi

Setelah migrasi

Menggunakan Guice untuk mengonfigurasi Framework Endpoint untuk Java

Maven

Gradle

Memverifikasi deployment baru

Menambahkan pengelolaan Endpoints API

Pemecahan masalah

API menampilkan 404 error, tetapi API Explorer tetap mencantumkan API dengan benar

API menampilkan error refleksi

Maven

Gradle

Sumber library klien tidak dikompilasi

Maven

Gradle

Masalah terkait peningkatan JPA/JDO Datanucleus

Maven

Gradle

API menampilkan `404` error, tetapi API Explorer tetap mencantumkan API dengan benar