Memanggil API backend dari klien Android

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

Catatan: Petunjuk ini mengasumsikan keakraban dengan pengembangan dan konsep Android, termasuk penyiapan project, class Activities dan AsyncTasks, preferensi bersama, izin Android, dan Intent. Jika Anda ingin mempelajari lebih lanjut konsep ini, lihat dokumentasi dan contoh Android.

Catatan: Untuk mengetahui informasi dan contoh kode yang menunjukkan cara mengakses backend API dari klien Python, lihat Mengakses backend API dari klien Python.

Membuat library klien

Klien Android Anda memerlukan library klien yang dibuat 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 direktori rekanan /src.

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

3. Klik kanan pustaka 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 menyediakannya dalam perintah. Android Studio menyediakan penyelesaian kode untuk mengidentifikasi panggilan metode yang tersedia, dan parameter yang diperlukan.

Penting untuk diperhatikan bahwa karena panggilan API menghasilkan permintaan melalui jaringan, Anda harus membuat permintaan di threadnya sendiri. (Persyaratan ini ditambahkan ke versi Android terbaru, tetapi merupakan praktik terbaik bahkan di versi lama.) Untuk melakukannya, Anda menggunakan 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 pengodean klien yang perlu Anda tambahkan. Mereka mengasumsikan bahwa Anda telah menambahkan dukungan Endpoints Frameworks untuk autentikasi seperti yang dijelaskan dalam Mengautentikasi pengguna.

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

• Konfigurasi Klien Android Anda untuk memberikan kredensial ke objek layanan.
• Gunakan pemilih akun untuk mendukung pilihan pengguna terkait akun login.

Bagian berikut memberikan detailnya.

Mengonfigurasi klien Android untuk memberikan kredensial

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

Mendapatkan kredensial pengguna dan menggunakan pemilih akun mengharuskan Anda 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 ID klien web dari backend API.

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;
}

Contoh kode 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 Anda.

Perhatikan bahwa contoh kode memeriksa untuk melihat apakah aplikasi Android sudah mengetahui akun mana yang akan digunakan atau tidak. Jika ya, alur logis dapat dilanjutkan 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 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);
}

Handler 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 backend API yang berjalan di App Engine produksi kapan saja tanpa melakukan perubahan apa pun. Namun, jika Anda 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 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 Menguji 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 terhubung ke panggilan API backend oleh klien Android) 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. Bangun ulang project klien Android Anda.

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

   1. Di Android Studio, buka Tools > Android > AVD Manager, lalu mulai AVD yang ada jika Anda memilikinya, atau buat AVD, lalu mulai AVD tersebut.
   2. Buka Run > Debug YOUR_PROJECT_NAME dengan YOUR_PROJECT_NAME mewakili nama project Google Cloud Anda.
   3. Jika 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 backend API dilindungi dengan Autentikasi, 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 terhadap upaya login pengguna. Sebagai gantinya, proses login terjadi begitu saja, sehingga memberikan akses 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.