Tutorial: Chamar uma API Web protegida no aplicativo Android

Aplica-se a: Locatários da força de trabalho Locatários externos (saiba mais)

Este é o terceiro tutorial da série de tutoriais que orienta você a chamar uma API Web protegida usando a ID Externa do Microsoft Entra.

Neste tutorial, você:

• Chamar uma API Web protegida

Pré-requisitos

Configuração de locatário da força de trabalho

• Tutorial: Adicionar entrada a um aplicativo Android usando a plataforma de identidade da Microsoft

Configuração de locatário externo

• Tutorial: Adicionar entrada a um aplicativo Android usando a plataforma de identidade da Microsoft

• Um registro de API que expõe pelo menos um escopo (permissões delegadas) e uma função de aplicativo (permissão de aplicativo), como ToDoList.Read. Caso ainda não tenha feito isso, siga as instruções para chamar uma API em um aplicativo móvel Android de exemplo para ter uma API Web do ASP.NET Core protegida funcionalmente. Conclua as seguintes etapas:

  • Registrar um aplicativo da API Web
  • Configurar escopos de API
  • Configurar funções de aplicativo
  • Configurar declarações opcionais
  • Clonar ou baixar a API Web de exemplo
  • Configurar e executar a API Web de exemplo

Chamar uma API Web protegida

Configuração de locatário da força de trabalho

1. Em app>src>main>java>com.example(nome do seu aplicativo). Crie os seguintes fragmentos Android:

   • Invólucro MSGraphRequestWrapper

2. Abra MSGraphRequestWrapper.java e substitua o código pelo seguinte snippet de código para chamar a API do Microsoft Graph usando o token fornecido pela MSAL:

    package com.azuresamples.msalandroidapp;
   
    import android.content.Context;
    import android.util.Log;
   
    import androidx.annotation.NonNull;
   
    import com.android.volley.DefaultRetryPolicy;
    import com.android.volley.Request;
    import com.android.volley.RequestQueue;
    import com.android.volley.Response;
    import com.android.volley.toolbox.JsonObjectRequest;
    import com.android.volley.toolbox.Volley;
   
    import org.json.JSONObject;
   
    import java.util.HashMap;
    import java.util.Map;
   
    public class MSGraphRequestWrapper {
        private static final String TAG = MSGraphRequestWrapper.class.getSimpleName();
   
        // See: https://docs.microsoft.com/en-us/graph/deployments#microsoft-graph-and-graph-explorer-service-root-endpoints
        public static final String MS_GRAPH_ROOT_ENDPOINT = "https://graph.microsoft.com/";
   
        /**
         * Use Volley to make an HTTP request with
         * 1) a given MSGraph resource URL
         * 2) an access token
         * to obtain MSGraph data.
         **/
        public static void callGraphAPIUsingVolley(@NonNull final Context context,
                                                   @NonNull final String graphResourceUrl,
                                                   @NonNull final String accessToken,
                                                   @NonNull final Response.Listener<JSONObject> responseListener,
                                                   @NonNull final Response.ErrorListener errorListener) {
            Log.d(TAG, "Starting volley request to graph");
   
            /* Make sure we have a token to send to graph */
            if (accessToken == null || accessToken.length() == 0) {
                return;
            }
   
            RequestQueue queue = Volley.newRequestQueue(context);
            JSONObject parameters = new JSONObject();
   
            try {
                parameters.put("key", "value");
            } catch (Exception e) {
                Log.d(TAG, "Failed to put parameters: " + e.toString());
            }
   
            JsonObjectRequest request = new JsonObjectRequest(Request.Method.GET, graphResourceUrl,
                    parameters, responseListener, errorListener) {
                @Override
                public Map<String, String> getHeaders() {
                    Map<String, String> headers = new HashMap<>();
                    headers.put("Authorization", "Bearer " + accessToken);
                    return headers;
                }
            };
   
            Log.d(TAG, "Adding HTTP GET to Queue, Request: " + request.toString());
   
            request.setRetryPolicy(new DefaultRetryPolicy(
                    3000,
                    DefaultRetryPolicy.DEFAULT_MAX_RETRIES,
                    DefaultRetryPolicy.DEFAULT_BACKOFF_MULT));
            queue.add(request);
        }
    }
   

Configuração de locatário externo

1. Para chamar uma API Web de um aplicativo Android para acessar dados ou serviços externos, comece criando um objeto complementar em sua MainActivity classe. O objeto complementar deve incluir o seguinte código:

   companion object {
       private const val WEB_API_BASE_URL = "" // Developers should set the respective URL of their web API here
       private const val scopes = "" // Developers should append the respective scopes of their web API.
   }
   

   O objeto complementar define duas constantes privadas: WEB_API_BASE_URL, em que os desenvolvedores definem a URL de sua API Web e scopes, em que os desenvolvedores acrescentam a respectiva scopes API Web.

2. Para lidar com o processo de acesso a uma API Web, use o seguinte código:

   private fun accessWebApi() {
       CoroutineScope(Dispatchers.Main).launch {
           binding.txtLog.text = ""
           try {
               if (WEB_API_BASE_URL.isBlank()) {
                   Toast.makeText(this@MainActivity, getString(R.string.message_web_base_url), Toast.LENGTH_LONG).show()
                   return@launch
               }
               val apiResponse = withContext(Dispatchers.IO) {
                   ApiClient.performGetApiRequest(WEB_API_BASE_URL, accessToken)
               }
               binding.txtLog.text = getString(R.string.log_web_api_response)  + apiResponse.toString()
           } catch (exception: Exception) {
               Log.d(TAG, "Exception while accessing web API: $exception")
   
               binding.txtLog.text = getString(R.string.exception_web_api) + exception
           }
       }
   }
   

   O código inicia uma corrotina no dispatcher principal. Ele começa limpando o log de texto. Em seguida, verifica se a URL base da API Web está em branco; se estiver, exibe uma mensagem de aviso e retorna. Em seguida, ele executa uma solicitação GET para a API Web usando o token de acesso fornecido em um thread em segundo plano.

   Depois de receber a resposta da API, ela atualiza o log de texto com o conteúdo da resposta. Se ocorrer alguma exceção durante esse processo, ela registrará a exceção e atualizará o log de texto com a mensagem de erro correspondente.

   No código, onde especificamos nosso retorno de chamada, usamos uma função chamada performGetApiRequest(). A função deve ter o seguinte código:

   object ApiClient {
       private val client = OkHttpClient()
   
       fun performGetApiRequest(WEB_API_BASE_URL: String, accessToken: String?): Response {
           val fullUrl = "$WEB_API_BASE_URL/api/todolist"
   
           val requestBuilder = Request.Builder()
                   .url(fullUrl)
                   .addHeader("Authorization", "Bearer $accessToken")
                   .get()
   
           val request = requestBuilder.build()
   
           client.newCall(request).execute().use { response -> return response }
       }
   }
   

   O código facilita criar GET solicitações para uma API Web. O método principal é performGetApiRequest(), que usa a URL base da API Web e um token de acesso como parâmetros. Dentro desse método, ele constrói uma URL completa acrescentando /api/todolist à URL base. Em seguida, ele cria uma solicitação HTTP com os cabeçalhos apropriados, incluindo o cabeçalho de autorização com o token de acesso.

   Por fim, ele executa a solicitação de forma síncrona usando o método okHttp newCall() e retorna a resposta. O objeto ApiClient mantém uma instância de OkHttpClient para manipular solicitações HTTP. Para usar OkHttpClient, você precisa adicionar a dependência implementation 'com.squareup.okhttp3:okhttp:4.9.0' ao arquivo Gradle do Android.

   Certifique-se de incluir as declarações de importação. O Android Studio deve incluir automaticamente para você as instruções de importação.

Testar seu aplicativo

Compilar e implantar o aplicativo em um emulador ou dispositivo de teste. Você deve conseguir entrar e obter tokens para o Microsoft Entra ID.

Conteúdo relacionado

• Cenário: Aplicativo móvel que chama APIs Web
• Exemplo de código para cenários complexos