Bermigrasi ke Cloud Endpoints Frameworks versi 2.0 untuk App Engine

Halaman ini menjelaskan cara memigrasikan aplikasi Cloud Endpoints versi 1.0 yang ada ke Endpoints Frameworks for App Engine di Java.

Catatan: Halaman ini menyebutkan Endpoints 1.0 sebagai Endpoints Frameworks versi 1.0 dan Endpoints Frameworks baru untuk App Engine sebagai Endpoints Frameworks versi 2.0.

Manfaat

Framework baru ini memberikan sejumlah manfaat, termasuk:

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

Endpoints Frameworks versi 2.0 tidak memengaruhi antarmuka ke API Anda. Klien yang ada akan terus berfungsi setelah migrasi tanpa perubahan kode sisi klien.

Fitur dan alat yang saat ini dikecualikan

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

• Protokol JSON-RPC, yang diperlukan untuk klien iOS lama. Untuk membuat klien iOS untuk API Endpoints Frameworks versi 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 Endpoints 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. JAR dasar yang diperlukan ada di artefak endpoints-framework. Jika Anda ingin menggunakan konfigurasi Guice, tambahkan artefak endpoints-framework-guice.

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

Catatan: Jika Anda menggunakan Endpoints Frameworks versi 1.0 dengan Eclipse,konversikan project Anda menjadi project Maven terlebih dahulu, lalu ikuti petunjuk Maven di bawah.

1. Download dan inisialisasi Google Cloud CLI.
2. Jalankan perintah berikut:
   1. Pastikan gcloud CLI diizinkan 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

Bermigrasi menggunakan Maven atau Gradle

Maven

1. Hapus dependensi lama, yaitu artefak appengine-endpoints:
   <dependency>
         <groupId>com.google.appengine</groupId>
         <artifactId>appengine-endpoints</artifactId>
         <version>1.9.53</version>
   </dependency>

2. Tambahkan dependensi Endpoints Frameworks baru:
   <dependency>
       <groupId>com.google.endpoints</groupId>
       <artifactId>endpoints-framework</artifactId>
       <version>2.2.1</version>
   </dependency>

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

4. Tambahkan plugin Maven App Engine 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 Maven App Engine lama, dengan grup com.google.appengine, tidak kompatibel dengan plugin Endpoints Frameworks. Anda harus menggunakan versi baru.
5. Perbarui titik entri API di file web.xml project Anda:
   • Mengganti nama semua kemunculan SystemServiceServlet menjadi EndpointsServlet
   • Ganti semua kemunculan jalur /_ah/spi/ dengan jalur baru yang diperlukan /_ah/api/
     

   Berikut ini menunjukkan isi web.xml sebelum dan setelah migrasi:

   Sebelum migrasi

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

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

6. Setelah mengubah dependensi, bersihkan project:

   mvn clean

7. Anda dapat membuat dokumen penemuan:

   mvn endpoints-framework:discoveryDocs

   Pelajari lebih lanjut tujuan plugin Maven Endpoints Frameworks.
8. 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. Tindakan ini dilakukan secara otomatis jika Anda tidak menentukan versi. Lihat Masalah umum.

Gradle

1. Hapus dependensi lama, yaitu artefak appengine-endpoints:

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

2. Tambahkan dependensi Endpoints Frameworks baru:
   compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'

3. Tambahkan plugin App Engine dan Endpoints Frameworks 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'
     }
   }

4. Terapkan plugin App Engine dan Endpoints Frameworks yang baru:
   apply plugin: 'com.google.cloud.tools.appengine'
   apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

5. Tentukan endpoint nama host untuk dokumen penemuan yang dihasilkan:
   endpointsServer {
     // Endpoints Framework Plugin server-side configuration
     hostname = "YOUR-PROJECT-ID.appspot.com"
   }

6. Perbarui titik entri API di file web.xml project Anda:
   • Mengganti nama semua kemunculan SystemServiceServlet menjadi EndpointsServlet
   • Ganti semua kemunculan jalur /_ah/spi/ dengan jalur baru yang diperlukan /_ah/api/
     

   Berikut ini menunjukkan isi web.xml sebelum dan setelah migrasi:

   Sebelum migrasi

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

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

7. Setelah mengubah dependensi, bersihkan project menggunakan:

   gradle clean

8. Anda dapat membuat dokumen penemuan menggunakan:

   gradle endpointsDiscoveryDocs

   Pelajari lebih lanjut tugas plugin Gradle Endpoints Frameworks
9. 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. Tindakan ini dilakukan secara otomatis jika Anda tidak menentukan versi. Lihat Masalah umum.

Menggunakan Guice untuk mengonfigurasi Endpoints Frameworks for Java

Jika Anda ingin menggunakan Guice:

1. Tambahkan dependensi Guice Endpoints Frameworks 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'

2. 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 melayani traffic:

1. Kirim beberapa permintaan ke deployment baru.

2. Di Google Cloud konsol, buka halaman Logging > Logs Explorer.

   Buka halaman Logs Explorer

3. Jika permintaan ditampilkan dengan jalur yang dimulai dengan /_ah/api, berarti Endpoints Frameworks versi 2.0 kini melayani API Anda. Log tidak boleh menampilkan permintaan dengan jalur yang dimulai dengan /_ah/spi. Permintaan ini menunjukkan bahwa proxy Endpoints Frameworks versi 1.0 masih melayani permintaan.

Menambahkan pengelolaan API Endpoints

Endpoints Frameworks 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 yang umum saat bermigrasi ke Endpoints Frameworks versi 2.0 dan solusi yang disarankan.

API menampilkan error 404, tetapi API Explorer masih 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 dalam konfigurasi aplikasi, layanan Endpoints akan terus memperlakukan aplikasi sebagai aplikasi versi 1.0. Anda mungkin melihat permintaan di log App Engine yang dikirim ke /_ah/spi, yang menghasilkan error HTTP 404 yang dikirim ke klien.

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

2. 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 mengemas artefak endpoints-framework ke dalam aplikasi, bukan JAR appengine-endpoints lama. Jika men-deploy aplikasi dengan kedua JAR, Anda mungkin 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 dependensi Anda yang lain bergantung pada Guava versi lama, hal ini juga dapat muncul sebagai metode TypeToken yang tidak ada. Anda harus memastikan bahwa Anda menggunakan Guava v19 atau menggunakan artefak endpoints-framework-all, yang menggantikan 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), maka aplikasi klien Anda kemungkinan bergantung pada versi lama library klien Google Java. 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 Datanucleus JPA/JDO

Maven

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

• Petunjuk JDO
• Petunjuk JPA

Gradle

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