Memanggil API backend dari klien Android

Halaman ini menjelaskan cara klien Android memanggil API backend yang dibuat dengan Framework Cloud Endpoints untuk App Engine.

Catatan: Petunjuk ini mengasumsikan bahwa Anda telah memahami pengembangan dan konsep Android, termasuk penyiapan project, class Aktivitas dan LiveData, preferensi bersama, izin Android, dan Intent. Jika Anda ingin mempelajari konsep ini lebih lanjut, lihat dokumentasi dan contoh Android.

Membuat library klien

Klien Android Anda memerlukan library klien yang dihasilkan dari API backend yang digunakan klien Anda. Jika Anda belum memiliki library klien, lihat Membuat library klien untuk mengetahui detailnya. Ada beberapa langkah dalam dokumen ini yang menjelaskan cara menambahkan library klien ke project klien Android.

Menyiapkan project

Dalam petunjuk ini, gunakan Android Studio. Jika belum melakukannya, Anda harus menyiapkan Android Studio untuk mendukung klien yang menggunakan framework tersebut.

Mengonfigurasi project

Di Android Studio, project Anda menggunakan file build.gradle untuk dependensi dan setelan lainnya. Secara default, Android Studio membuat file build.gradle level project induk dan file khusus aplikasi Android dalam modul Android. Petunjuk ini ditujukan untuk build.gradle khusus aplikasi dalam modul Android.

Untuk mengonfigurasi build.gradle:

1. Klik dua kali build.gradle untuk membukanya.

2. Edit file ini sehingga berisi baris berikut:

   buildscript {
       repositories {
           mavenCentral()
       }
       dependencies {
           classpath 'com.android.tools.build:gradle:1.0.0'
       }
   }
   apply plugin: 'com.android.application'
   
   repositories {
       mavenCentral()
       mavenLocal()
   }
   
   android {
       compileSdkVersion 26
   
       defaultConfig {
           applicationId "com.mycompany.myapp"
           minSdkVersion 17
           targetSdkVersion 26
           versionCode 1
           versionName "1.0"
       }
       buildTypes {
           release {
               minifyEnabled false
               proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
           }
       }
       packagingOptions {
           exclude 'META-INF/DEPENDENCIES'
       }
   }
   
   dependencies {
       implementation 'com.android.support:appcompat-v7:26.1.0'
       implementation 'com.android.support.constraint:constraint-layout:1.1.3'
       // BEGIN Google APIs
       // Play Services will validate the application prior to allowing OAuth2 access.
       implementation 'com.google.android.gms:play-services-auth:16.0.0'
       implementation 'com.google.android.gms:play-services-identity:16.0.0'
       // The following lines implement maven imports as defined at:
       // https://github.com/googleapis/google-api-java-client/wiki/Setup-Instructions
       // Add the Google API client library.
       implementation('com.google.api-client:google-api-client:1.28.0') {
           // Exclude artifacts that the Android SDK/Runtime provides.
           exclude(group: 'xpp3', module: 'xpp3')
           exclude(group: 'org.apache.httpcomponents', module: 'httpclient')
           exclude(group: 'junit', module: 'junit')
           exclude(group: 'com.google.android', module: 'android')
       }
       // Add the Android extensions for the Google API client library.
       // This will automatically include play services as long as you have download that library
       // from the Android SDK manager.
       // Add the Android extensions for the Google API client library.
       implementation(group: 'com.google.api-client', name: 'google-api-client-android', version: '1.25.0') {
                  // Exclude play services, since we're not using this yet.
                 exclude(group: 'com.google.android.gms:play-services', module: 'google-play-services')
       }
       // END Google APIs
       // The following client libraries make HTTP/JSON on Android easier.
       // Android extensions for Google HTTP Client.
       implementation('com.google.http-client:google-http-client-android:1.21.0') {
           exclude(group: 'com.google.android', module: 'android')
       }
       implementation 'com.google.http-client:google-http-client-gson:1.21.0'
       // This is used by the Google HTTP client library.
       implementation 'com.google.guava:guava:18.0+'
       implementation files('libs/echo-v1-1.25.0-SNAPSHOT.jar')
   }
   
   

   Ganti com.mycompany.myapp dengan nilai Anda sendiri.

3. Klik File > Save All, lalu keluar dari Android Studio dan mulai ulang.

Menambahkan library klien ke project

Untuk menambahkan library klien ke project Android:

1. Tambahkan direktori /libs ke project Anda jika belum memilikinya. Ini adalah peer ke direktori /src.

2. Salin library klien yang dibuat dari API backend ke /libs.

3. Klik kanan library yang baru saja Anda tambahkan, lalu pilih Add As Library ke project Anda.

Membuat objek layanan

Dalam kode project, Anda harus menggunakan objek layanan untuk membuat permintaan ke API backend. Untuk permintaan unauthenticated, buat objek layanan seperti berikut:

BACKEND_API_NAME.Builder builder = new BACKEND_API_NAME.Builder(
    NetHttpTransport(), new GsonFactory(), null);
service = builder.build();

Ganti BACKEND_API_NAME dengan nama API backend Anda.

Penting: Untuk panggilan yang diautentikasi, Anda harus memberikan kredensial ke objek layanan, seperti yang dijelaskan dalam Melakukan panggilan yang diautentikasi.

Memanggil backend API

Dalam project Anda, panggil API menggunakan objek layanan. Contoh:

ScoreCollection scores = service.scores().list().execute();

Dalam cuplikan ini, Anda meminta daftar semua objek Score di server. Jika list memerlukan parameter, atau isi permintaan, Anda harus menyediakannya dalam perintah. Android Studio menyediakan pelengkapan kode untuk mengidentifikasi panggilan metode yang tersedia, dan parameter yang diperlukan.

Penting untuk diperhatikan bahwa karena panggilan API menyebabkan permintaan melalui jaringan, Anda harus membuat permintaan di threadnya sendiri. (Persyaratan ini telah ditambahkan ke versi terbaru Android, tetapi merupakan praktik terbaik bahkan dalam versi yang lebih lama.) Untuk melakukannya, gunakan Thread atau AsyncTask. Contoh:

private class QueryScoresTask extends AsyncTask<Void, Void, ScoreCollection>{
  Context context;

  public QueryScoresTask(Context context) {
    this.context = context;
  }

  protected Scores doInBackground(Void... unused) {
    ScoreCollection scores = null;
    try {
      scores = service.scores().list().execute();
    } catch (IOException e) {
      Log.d("TicTacToe", e.getMessage(), e);
    }
    return scores;
  }

  protected void onPostExecute(ScoreCollection scores) {
    // Do something with the result.
  }
}

Melakukan panggilan yang diautentikasi

Penting: Untuk mengetahui informasi tentang autentikasi dari perspektif menjaga keamanan backend, lihat postingan blog Memverifikasi panggilan backend dari aplikasi Android.

Petunjuk ini hanya mencakup coding klien yang perlu Anda tambahkan. Mereka berasumsi bahwa Anda telah menambahkan dukungan Framework Endpoint untuk autentikasi seperti yang dijelaskan dalam Mengautentikasi pengguna.

Jika klien Android melakukan panggilan ke endpoint yang memerlukan autentikasi, Anda harus:

• Konfigurasikan Klien Android Anda untuk memberikan kredensial ke objek layanan.
• Gunakan alat pilih akun untuk mendukung pilihan pengguna atas akun login.

Bagian berikut memberikan detailnya.

Mengonfigurasi klien Android Anda untuk memberikan kredensial

Untuk mendukung permintaan ke API backend yang memerlukan autentikasi, klien Android Anda perlu mendapatkan kredensial pengguna dan meneruskannya ke objek layanan.

Untuk mendapatkan kredensial pengguna dan menggunakan pemilih akun, Anda harus memiliki izin Android berikut:

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />

Untuk mendapatkan kredensial pengguna, panggil GoogleAccountCredential.usingAudience sebagai berikut:

// Inside your Activity class onCreate method
settings = getSharedPreferences(
    "TicTacToeSample", 0);
credential = GoogleAccountCredential.usingAudience(this,
    "server:client_id:1-web-app.apps.googleusercontent.com");

Dengan parameter kedua untuk panggilan adalah awalan server:client_id yang ditambahkan ke client ID web dari API backend.

Kode contoh: mendapatkan kredensial untuk objek layanan

Kode berikut menunjukkan cara mendapatkan kredensial dan meneruskannya ke objek layanan:

// Inside your Activity class onCreate method
settings = getSharedPreferences("TicTacToeSample", 0);
credential = GoogleAccountCredential.usingAudience(this,
    "server:client_id:1-web-app.apps.googleusercontent.com");
setSelectedAccountName(settings.getString(PREF_ACCOUNT_NAME, null));

Tictactoe.Builder builder = new Tictactoe.Builder(
    NetHttpTransport(), new GsonFactory(),
    credential);
service = builder.build();

if (credential.getSelectedAccountName() != null) {
  // Already signed in, begin app!
} else {
  // Not signed in, show login window or request an account.
}

// setSelectedAccountName definition
private void setSelectedAccountName(String accountName) {
  SharedPreferences.Editor editor = settings.edit();
  editor.putString(PREF_ACCOUNT_NAME, accountName);
  editor.commit();
  credential.setSelectedAccountName(accountName);
  this.accountName = accountName;
}

Kode contoh sebelumnya mencari semua preferensi bersama yang disimpan oleh aplikasi Android dan mencoba menemukan nama akun yang ingin digunakan pengguna untuk melakukan autentikasi ke aplikasi Anda. Jika berhasil, kode akan membuat objek kredensial dan meneruskannya ke objek layanan Anda. Dengan kredensial ini, aplikasi Android Anda dapat meneruskan token yang sesuai ke backend.

Perhatikan bahwa contoh kode ini memeriksa apakah aplikasi Android sudah mengetahui akun mana yang akan digunakan. Jika ya, alur logis dapat melanjutkan dan menjalankan aplikasi Android. Jika aplikasi tidak mengetahui akun mana yang akan digunakan, aplikasi akan menampilkan layar login atau meminta pengguna untuk memilih akun.

Terakhir, sampel akan membuat objek kredensial dan meneruskannya ke objek layanan. Kredensial ini memungkinkan aplikasi Android Anda meneruskan token yang sesuai ke aplikasi web App Engine Anda.

Menggunakan pemilih akun

Android menyediakan intent untuk memilih akun pengguna. Anda dapat memanggilnya sebagai berikut:

static final int REQUEST_ACCOUNT_PICKER = 2;

void chooseAccount() {
  startActivityForResult(credential.newChooseAccountIntent(),
      REQUEST_ACCOUNT_PICKER);
}

Pengendali untuk menafsirkan hasil intent ini ditampilkan di sini:

@Override
protected void onActivityResult(int requestCode, int resultCode,
   Intent data) {
 super.onActivityResult(requestCode, resultCode, data);
 switch (requestCode) {
   case REQUEST_ACCOUNT_PICKER:
     if (data != null && data.getExtras() != null) {
       String accountName =
           data.getExtras().getString(
               AccountManager.KEY_ACCOUNT_NAME);
       if (accountName != null) {
         setSelectedAccountName(accountName);
         SharedPreferences.Editor editor = settings.edit();
         editor.putString(PREF_ACCOUNT_NAME, accountName);
         editor.commit();
         // User is authorized.
       }
     }
     break;
  }
}

Menguji klien Android terhadap server pengembangan lokal

Anda dapat menguji klien terhadap API backend yang berjalan di App Engine produksi kapan saja tanpa melakukan perubahan apa pun. Namun, jika ingin menguji klien terhadap API backend yang berjalan di server pengembangan lokal, Anda perlu mengubah baris kode di klien agar mengarah ke alamat IP mesin yang menjalankan server pengembangan lokal.

Catatan: Anda dapat menggunakan emulator Perangkat Virtual Android (AVD) atau perangkat fisik. Namun, perangkat fisik harus menggunakan Wi-Fi yang sama dengan sistem yang menjalankan server pengembangan lokal.

Untuk membuat perubahan yang diperlukan dan menguji menggunakan server pengembangan lokal:

1. Catat alamat IP komputer yang menjalankan server pengembangan lokal karena Anda akan memerlukannya saat menambahkan kode ke klien Android.

2. Mulai server pengembangan lokal, seperti yang dijelaskan dalam Menjalankan dan menguji backend API secara lokal.

3. Dalam project klien Android Studio, cari kode yang mendapatkan handle ke layanan API backend. Biasanya, kode ini menggunakan Builder untuk menyiapkan permintaan API.

4. Ganti URL root pada objek Builder (ini adalah URL yang terhubung ke klien Android di panggilan API backend) dengan menambahkan baris:

   yourBuilderObject.setRootUrl("http://YOUR_MACHINE_IP_ADDRESS:8080/_ah/api");
   

   Contoh:

   public static Helloworld getApiServiceHandle(@Nullable GoogleAccountCredential credential) {
     // Use a builder to help formulate the API request.
     Helloworld.Builder helloWorld = new Helloworld.Builder(AppConstants.HTTP_TRANSPORT,
         AppConstants.JSON_FACTORY,credential);
   
     helloWorld.setRootUrl("http://YOUR_MACHINE_IP_ADDRESS:8080/_ah/api");
     return helloWorld.build();
   }
   

   Ganti YOUR_MACHINE_IP_ADDRESS dengan alamat IP sistem Anda.

5. Build ulang project klien Android Anda.

6. Jika Anda ingin menjalankan aplikasi klien pada emulator AVD:

   1. Di Android Studio, buka Tools > Android > AVD Manager dan mulai AVD yang ada jika Anda memilikinya, jika tidak, buat AVD, lalu mulai.
   2. Buka Run > Debug YOUR_PROJECT_NAME dengan YOUR_PROJECT_NAME mewakili nama project Google Cloud Anda.
   3. Saat diminta memilih perangkat, pilih AVD Anda.
   4. Uji klien Anda.

7. Jika Anda ingin menjalankan aplikasi klien di perangkat Android fisik:

   1. Pastikan perangkat Android Anda diaktifkan untuk proses debug.
   2. Di Android Studio, buka Run > Debug YOUR_PROJECT_NAME.
   3. Saat diminta memilih perangkat, pilih perangkat Android fisik Anda.
   4. Uji klien Anda.

Penting: Jika API backend dilindungi Auth, klien Anda harus memberikan dukungan seperti yang dijelaskan dalam Menambahkan dukungan autentikasi dengan OAuth 2.0. Namun, saat dijalankan terhadap server pengembangan lokal, tidak ada halaman kredensial yang ditampilkan sebagai respons atas upaya pengguna untuk login. Sebagai gantinya, proses login akan dilakukan dengan memberi pengguna akses ke API yang dilindungi, dan pengguna yang ditampilkan selalu [e-mail].

Contoh kode sumber klien

Untuk kode contoh, lihat contoh Android Cloud Endpoints v2.0.