Memanggil API backend dari klien Android

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

Catatan: Petunjuk ini mengasumsikan bahwa Anda sudah memahami pengembangan dan konsep Android, termasuk penyiapan project, class Activities dan AsyncTasks, 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 langkah-langkah dalam dokumen ini yang menjelaskan cara menambahkan library klien ke project klien Android.

Menyiapkan project

Dalam petunjuk ini, Anda akan menggunakan Android Studio. Jika belum melakukannya, Anda perlu menyiapkan Android Studio untuk mendukung klien yang menggunakan framework.

Mengonfigurasi project

Di Android Studio, project Anda menggunakan file build.gradle untuk dependensi dan setelan lainnya. Secara default, Android Studio membuat file build.gradle tingkat project induk dan file khusus aplikasi Android di modul Android. Petunjuk ini ditujukan untuk build.gradle khusus aplikasi di 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 ada. Direktori ini adalah peer untuk direktori /src.

2. Salin library klien yang dihasilkan 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 yang tidak diautentikasi, buat objek layanan sebagai 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 API backend

Di 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 memberikannya dalam perintah. Android Studio menyediakan penyelesaian kode untuk mengidentifikasi panggilan metode yang tersedia, dan parameter yang diperlukannya.

Perhatikan bahwa karena panggilan API menghasilkan permintaan melalui jaringan, Anda harus membuat permintaan di thread-nya sendiri. (Persyaratan ini ditambahkan ke Android versi terbaru, tetapi ini adalah praktik terbaik bahkan di versi 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 informasi tentang autentikasi dari perspektif menjaga backend tetap aman, lihat postingan blog Memverifikasi panggilan backend dari aplikasi Android.

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

Jika klien Android Anda 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 akun login pengguna.

Bagian berikut memberikan detail.

Mengonfigurasi klien Android untuk memberikan kredensial

Untuk mendukung permintaan ke API backend yang memerlukan autentikasi, klien Android Anda harus 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, Anda memanggil 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 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 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. Kredensial ini memungkinkan aplikasi Android Anda meneruskan token yang sesuai ke backend.

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

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

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 perlu 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 melakukan perubahan yang diperlukan dan menguji menggunakan server pengembangan lokal:

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

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

3. Di project klien Android Studio, temukan 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 dihubungkan klien Android dalam 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 di emulator AVD:

   1. Di Android Studio, buka Tools > Android > AVD Manager dan mulai AVD yang ada jika Anda memilikinya, atau buat AVD, lalu mulai.
   2. Buka Run > Debug YOUR_PROJECT_NAME dengan YOUR_PROJECT_NAME mewakili nama project Google Cloud Anda.
   3. Jika diminta untuk 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. Jika 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 berjalan di server pengembangan lokal, tidak ada halaman kredensial yang ditampilkan sebagai respons terhadap upaya pengguna untuk login. Sebagai gantinya, login akan terjadi, yang memberikan akses kepada pengguna 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.