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:

  1. Download dan lakukan inisialisasi Google Cloud CLI.
  2. 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

  1. Hapus dependensi lama, yang merupakan 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 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>
  5. 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>

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

    Pelajari lebih lanjut sasaran plugin Maven App Engine.

Gradle

  1. Hapus dependensi lama, yang merupakan 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 Endpoints Frameworks 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 dibuat: 
    endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "YOUR-PROJECT-ID.appspot.com"
}
  6. 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>

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

    Pelajari lebih lanjut tugas plugin Gradle App Engine.

Menggunakan Guice untuk mengonfigurasi Framework Endpoint untuk Java

Jika Anda ingin menggunakan Guice:

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

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