Memanggil API web dari aplikasi mobile

Artikel
2025-03-05

Berlaku untuk: Lingkaran hijau dengan simbol tanda centang putih. Penyewa Tenaga Kerja Lingkaran putih dengan simbol X abu-abu. Penyewa Eksternal (baca lebih lanjut)

Setelah aplikasi Anda memasukkan pengguna dan menerima token, Microsoft Authentication Library (MSAL) mengekspos informasi tentang pengguna, lingkungan pengguna, dan token yang dikeluarkan. Aplikasi Anda dapat menggunakan nilai-nilai ini untuk memanggil API web atau menampilkan pesan selamat datang kepada pengguna.

Dalam artikel ini, pertama-tama kita akan melihat hasil dari MSAL. Kemudian kita akan melihat cara menggunakan token akses dari AuthenticationResult atau result untuk memanggil API web yang dilindungi.

Hasil MSAL

MSAL memberikan nilai berikut:

AccessToken memanggil API web yang dilindungi dalam permintaan pembawa HTTP.
IdToken berisi informasi yang berguna tentang pengguna yang masuk. Informasi ini mencakup nama pengguna, penyewa asal, dan pengidentifikasi unik untuk penyimpanan.
ExpiresOn adalah waktu kedaluwarsa token. MSAL menangani penyegaran otomatis aplikasi.
TenantId adalah pengidentifikasi penyewa tempat pengguna masuk. Untuk pengguna tamu di Microsoft Entra B2B, nilai ini mengidentifikasi penyewa tempat pengguna masuk. Nilai tidak mengidentifikasi penyewa asal pengguna.
Scopes menunjukkan cakupan yang diberikan dengan token Anda. Cakupan yang diberikan mungkin merupakan subset dari cakupan yang Anda minta.

MSAL juga memberikan abstraksi untuk nilai Account. Nilai Account menunjukkan akun masuk pengguna saat ini:

HomeAccountIdentifier mengidentifikasi penyewa asal pengguna.
UserName adalah nama pengguna pilihan pengguna. Nilai ini mungkin kosong untuk pengguna Microsoft Azure AD B2C.
AccountIdentifier mengidentifikasi pengguna yang masuk. Sering kali, nilai ini sama dengan nilai HomeAccountIdentifier kecuali pengguna adalah tamu di penyewa lain.

Panggil API

Setelah memiliki token akses, Anda dapat memanggil API web. Aplikasi Anda akan menggunakan token untuk membuat permintaan HTTP lalu menjalankan permintaan.

Android

        RequestQueue queue = Volley.newRequestQueue(this);
        JSONObject parameters = new JSONObject();

        try {
            parameters.put("key", "value");
        } catch (Exception e) {
            // Error when constructing.
        }
        JsonObjectRequest request = new JsonObjectRequest(Request.Method.GET, MSGRAPH_URL,
                parameters,new Response.Listener<JSONObject>() {
            @Override
            public void onResponse(JSONObject response) {
                // Successfully called Graph. Process data and send to UI.
            }
        }, new Response.ErrorListener() {
            @Override
            public void onErrorResponse(VolleyError error) {
                // Error.
            }
        }) {
            @Override
            public Map<String, String> getHeaders() throws AuthFailureError {
                Map<String, String> headers = new HashMap<>();

                // Put access token in HTTP request.
                headers.put("Authorization", "Bearer " + authResult.getAccessToken());
                return headers;
            }
        };

        request.setRetryPolicy(new DefaultRetryPolicy(
                3000,
                DefaultRetryPolicy.DEFAULT_MAX_RETRIES,
                DefaultRetryPolicy.DEFAULT_BACKOFF_MULT));
        queue.add(request);

MSAL untuk iOS dan macOS

Metode untuk memperoleh token menghasilkan objek MSALResult. MSALResult mengekspos properti accessToken. Anda dapat menggunakan accessToken untuk memanggil API web. Tambahkan properti ini ke header otorisasi HTTP sebelum Anda memanggil untuk mengakses API web yang dilindungi.

NSMutableURLRequest *urlRequest = [NSMutableURLRequest new];
urlRequest.URL = [NSURL URLWithString:"https://contoso.api.com"];
urlRequest.HTTPMethod = @"GET";
urlRequest.allHTTPHeaderFields = @{ @"Authorization" : [NSString stringWithFormat:@"Bearer %@", accessToken] };

NSURLSessionDataTask *task =
[[NSURLSession sharedSession] dataTaskWithRequest:urlRequest
     completionHandler:^(NSData * _Nullable data, NSURLResponse * _Nullable response, NSError * _Nullable error) {}];
[task resume];

let urlRequest = NSMutableURLRequest()
urlRequest.url = URL(string: "https://contoso.api.com")!
urlRequest.httpMethod = "GET"
urlRequest.allHTTPHeaderFields = [ "Authorization" : "Bearer \(accessToken)" ]

let task = URLSession.shared.dataTask(with: urlRequest as URLRequest) { (data: Data?, response: URLResponse?, error: Error?) in }
task.resume()

Membuat beberapa permintaan API

Untuk memanggil API yang sama beberapa kali, atau memanggil beberapa API, maka pertimbangkan subjek berikut saat Anda membuat aplikasi:

Persetujuan bertahap: Platform identitas Microsoft memungkinkan aplikasi untuk mendapatkan persetujuan pengguna ketika izin diperlukan alih-alih semuanya di awal. Setiap kali aplikasi Anda siap untuk memanggil API, aplikasi hanya akan meminta cakupan yang dibutuhkan.
Akses Bersyarat: Saat Anda membuat beberapa permintaan API, dalam skenario tertentu Anda mungkin harus memenuhi persyaratan akses bersyarat tambahan. Persyaratan dapat meningkat dengan cara ini jika permintaan pertama tidak memiliki kebijakan akses bersyarat dan aplikasi Anda mencoba mengakses API baru secara diam-diam yang memerlukan Akses Bersyarat. Untuk menangani masalah ini, pastikan untuk menangkap kesalahan dari permintaan senyap, dan bersiaplah untuk membuat permintaan interaktif. Untuk informasi selengkapnya, lihat Panduan Akses Bersyarat.

Cara memanggil beberapa API untuk pengguna yang sama, setelah Anda memperoleh token untuk pengguna, Anda dapat menghindari meminta kredensial kepada pengguna berulang kali dengan kemudian memanggil AcquireTokenSilent untuk mendapatkan token:

var result = await app.AcquireTokenXX("scopeApi1")
                      .ExecuteAsync();

result = await app.AcquireTokenSilent("scopeApi2")
                  .ExecuteAsync();

Interaksi diperlukan ketika:

Pengguna menyetujui API pertama tetapi sekarang perlu menyetujui lebih banyak cakupan. Dalam hal ini, Anda menggunakan persetujuan bertahap.
API pertama tidak memerlukan autentikasi multifaktor, tetapi API berikutnya memerlukannya.

var result = await app.AcquireTokenXX("scopeApi1")
                      .ExecuteAsync();

try
{
 result = await app.AcquireTokenSilent("scopeApi2")
                  .ExecuteAsync();
}
catch(MsalUiRequiredException ex)
{
 result = await app.AcquireTokenInteractive("scopeApi2")
                  .WithClaims(ex.Claims)
                  .ExecuteAsync();
}

Langkah berikutnya

Pelajari lebih lanjut dengan membangun aplikasi halaman tunggal React (SPA) yang memungkinkan pengguna masuk pada seri tutorial multi-bagian berikut.
Menjelajahi platform identitas Microsoft untuk sampel kode seluler

Bagikan melalui