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 Framework Endpoint untuk App Engine di Java.

Catatan: Halaman ini merujuk ke 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:

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

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 tersebut, kirimkan permintaan fitur.

• Protokol JSON-RPC, yang diperlukan untuk klien iOS lama. Untuk membuat klien iOS untuk API Endpoints Frameworks versi 2.0, sebaiknya Anda menggunakan 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 di grup com.google.endpoints. JAR dasar yang diperlukan ada dalam 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 lakukan inisialisasi Google Cloud CLI.
2. 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

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 Framework Endpoint. Anda harus menggunakan versi baru.
5. Perbarui titik entri API di file web.xml project Anda:
   • Mengganti nama semua kemunculan SystemServiceServlet menjadi EndpointsServlet
   • Mengganti semua kemunculan jalur /_ah/spi/ ke jalur baru yang diperlukan /_ah/api/
     

   Berikut ini menunjukkan konten 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 sasaran plugin Framework Endpoint Maven.
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 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'
     }
   }

4. Terapkan plugin App Engine dan Framework Endpoint 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
   • Mengganti semua kemunculan jalur /_ah/spi/ ke jalur baru yang diperlukan /_ah/api/
     

   Berikut ini menunjukkan konten 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 Framework Endpoint Gradle
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 Framework Endpoint untuk Java

Jika Anda ingin menggunakan Guice:

1. Tambahkan dependensi Guice Framework Endpoints 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, sebagai 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 menayangkan traffic:

1. Kirim beberapa permintaan ke deployment baru.

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

   Buka halaman Logs Explorer

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

Menambahkan pengelolaan Endpoints API

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

API menampilkan error 404, tetapi Penjelajah API 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 dalam 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 ada dependensi Anda yang lain yang 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 meng-shadow 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), aplikasi klien Anda mungkin bergantung pada library klien Google Java versi lama. Anda harus memastikan bahwa artefak google-api-client Anda 1.23.0 atau 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 dalam bentuk apa pun. Jika project Anda menggunakan dukungan peningkatan Datanucleus JDO atau JPA dari plugin lama, Anda harus mengonfigurasi plugin Maven Datanucleus pihak ketiga secara terpisah saat bermigrasi. Lihat informasi selengkapnya di sini:

• Petunjuk JDO
• Petunjuk JPA

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 baru. Lihat contoh dari Stackoverflow.