Tasks API unter Android verwenden

Warnung: Dieses Dokument wurde eingestellt. Informationen zur Autorisierung von Android-Apps mit OAuth 2.0 finden Sie in der Dokumentation zur Autorisierung der Android Play-Dienste.

In diesem Dokument wird erläutert, wie Sie die Tasks API mit OAuth 2.0 unter Android verwenden. Darin werden die Autorisierungsmechanismen beschrieben, mit denen Sie Zugriff auf die Google Tasks-Aufgaben eines Nutzers erhalten. Außerdem erfahren Sie, wie Sie ein einsatzbereites Service-Objekt des Tasks API in Ihrer Android-Anwendung bereitstellen können.

Damit Ihre Android-Anwendung die Tasks API verwenden kann, sind mehrere Schritte erforderlich:

  1. Das Google-Konto des Nutzers auswählen
  2. Rufen Sie im AccountManager ein OAuth 2.0-Zugriffstoken für die Task API ab.
  3. Projekt identifizieren und das Task-Dienstobjekt einrichten
  4. Tasks API aufrufen

Clientbibliothek von Google importieren

Für die Beispiele in diesem Dokument wird die Google API-Clientbibliothek für Java verwendet. Sie müssen die folgenden JAR-Dateien zu Ihrer Android-App hinzufügen. Legen Sie dazu die unten aufgeführten JAR-Dateien im Ordner /assets im Stammverzeichnis Ihrer Android-Anwendung ab. Prüfen Sie auch, ob dieses Dokument älter wird.

Importieren Sie die JAR-Dateien der Google API-Clientbibliothek und die zugehörigen Android-Erweiterungen (alles von google-api-java-client-1.4.1-beta.zip):

  • google-api-client-1.4.1-beta.jar
  • google-api-client-extensions-android2-1.4.1-beta.jar
  • google-api-client-googleapis-1.4.1-beta.jar
  • google-api-client-googleapis-extensions-android2-1.4.1-beta.jar

Importieren Sie die Tasks-spezifische JAR-Datei:

Importieren Sie Abhängigkeiten (alle Bestandteile von google-api-java-client-1.4.1-beta.zip):

  • commons-codec-1.3.jar
  • gson-1.6.jar
  • guava-r09.jar
  • httpclient-4.0.3.jar
  • httpcore-4.0.1.jar
  • jackson-core-asl-1.6.7.jar
  • jsr305-1.3.9.jar

Google-Konten in Android

Seit Android 2.0 verwaltet der AccountManager die Konten, die Sie in Ihrer Umgebung registriert haben, die unter Einstellungen > Konten & Synchronisierung aufgeführt sind. Insbesondere übernimmt er den Autorisierungsablauf und kann Autorisierungstokens generieren, die für den Datenzugriff über APIs erforderlich sind.

In Ihrer Android-Umgebung registrierte Konten
In Ihrer Android-Umgebung registrierte Konten

Um über den AccountManager Konten abrufen und Autorisierungstoken anfordern zu können, müssen Sie die folgenden Berechtigungen in Ihrem Android-Anwendungsmanifest hinzufügen:

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

Mit dem AccountManager können Sie das Google-Konto auswählen, mit dem Sie auf Tasks zugreifen möchten. Über den AccountManager werden nicht nur Google-Konten, sondern auch Konten von anderen Anbietern verwaltet. Fordern Sie daher ausdrücklich ein Google-Konto an, indem Sie den folgenden Code verwenden:

AccountManager accountManager = AccountManager.get(activity);
Account[] accounts = accountManager.getAccountsByType("com.google");

Alternativ enthält die Google API-Clientbibliothek für Java auch einen GoogleAccountManager, der nur Google-Konten verarbeitet:

GoogleAccountManager googleAccountManager = new GoogleAccountManager(activity);
Account[] accounts = googleAccountManager.getAccounts();

Wenn auf dem Android-Gerät mehr als ein Google-Konto verfügbar ist, sollten Sie den Nutzer auffordern, das gewünschte Konto anzugeben. Daraufhin erscheint ein Dialogfeld, das etwa so aussehen könnte:

Dialogfeld zum Auswählen des Kontos
Dialogfeld zum Auswählen des Kontos

Sie könnten ein solches Dialogfeld erstellen, indem Sie den folgenden Switch-/Case-Code in der Methode onCreateDialog Ihrer Aktivität verwenden:

@Override
protected Dialog onCreateDialog(int id) {
  switch (id) {
    case DIALOG_ACCOUNTS:
      AlertDialog.Builder builder = new AlertDialog.Builder(this);
      builder.setTitle("Select a Google account");
      final Account[] accounts = accountManager.getAccountsByType("com.google");
      final int size = accounts.length;
      String[] names = new String[[]size];
      for (int i = 0; i < size; i++) {
        names[[]i] = accounts[[]i].name;
      }
      builder.setItems(names, new DialogInterface.OnClickListener() {
        public void onClick(DialogInterface dialog, int which) {
          // Stuff to do when the account is selected by the user
          gotAccount(accounts[[]which]);
        }
      });
      return builder.create();
  }
  return null;
}

Wenn Sie showDialog(DIALOG_ACCOUNTS) aufrufen, wird das Dialogfeld für die Kontoauswahl angezeigt.

Google APIs-Autorisierungsablauf unter Android

Nachdem der Nutzer ein Konto ausgewählt hat, können wir den AccountManager bitten, ein OAuth 2.0-Zugriffstoken für die Task API auszustellen. Dazu rufen Sie die Methode AccountManager.getAuthToken() auf. Während des Aufrufs von AccountManager.getAuthToken() übernimmt AccountManager die Kontaktaufnahme mit dem Autorisierungsendpunkt der Google APIs. Wenn der AccountManager das Autorisierungstoken abgerufen hat, führt er den AccountManagerCallback aus, den Sie im Methodenaufruf definiert haben:

manager.getAuthToken(account, AUTH_TOKEN_TYPE, null, activity, new AccountManagerCallback<Bundle>() {
    public void run(AccountManagerFuture<Bundle> future) {
      try {
        // If the user has authorized your application to use the tasks API
        // a token is available.
        String token = future.getResult().getString(AccountManager.KEY_AUTHTOKEN);
        // Now you can use the Tasks API...
        useTasksAPI(token);
      } catch (OperationCanceledException e) {
        // TODO: The user has denied you access to the API, you should handle that
      } catch (Exception e) {
        handleException(e);
      }
    }
  }, null);

Wie Sie vielleicht bereits wissen, bietet der Android AccountManager experimentelle Unterstützung für OAuth 2.0. Sie müssen nur dem Bereich der API, auf die Sie zugreifen möchten, oauth2: voranstellen, wenn Sie AUTH_TOKEN_TYPE festlegen. Für die Tasks API können Sie also Folgendes verwenden:

String AUTH_TOKEN_TYPE = "oauth2:https://www.googleapis.com/auth/tasks";

Das Problem bei der Verwendung des obigen Werts als AUTH_TOKEN_TYPE besteht darin, dass der String oauth2:https://www.googleapis.com/auth/tasks im Autorisierungsdialog als Name des Google-Produkts angezeigt wird, auf das Sie zugreifen möchten. Um dieses Problem zu umgehen, gibt es spezielle, für Menschen lesbare AUTH_TOKEN_TYPE-Aliasse für die Tasks API. Sie entsprechen der Verwendung des OAuth 2.0-Bereichs. Sie können beispielsweise Folgendes verwenden:

String AUTH_TOKEN_TYPE = "Manage your tasks";

Sie können auch das Alias AUTH_TOKEN_TYPE für Aufgaben ansehen verwenden. Dies entspricht dem Lesezugriff der Tasks API: oauth2:https://www.googleapis.com/auth/tasks.readonly.

Während des Aufrufs von AccountManager.getAuthToken() überprüft der AccountManager, ob Ihre Anwendung für den Zugriff auf die Tasks API autorisiert wurde. Wenn Ihre Anwendung noch nicht autorisiert wurde, wird vom AccountManager eine Aktivität gestartet. Dem Nutzer wird ein Dialogfeld zur Autorisierung angezeigt, über das er die Verwendung der Tasks API in seinem Konto für Ihre Anwendung zulassen oder verweigern kann.

Dialogfeld „Autorisierung“
Dialogfeld „Autorisierung“

Wenn der Nutzer Ihrer Anwendung den Zugriff auf die Tasks API verweigert, wird während des Aufrufs future.getResult() eine OperationCanceledException ausgelöst. Sie sollten dies souverän handhaben, indem Sie beispielsweise auffordern, das Konto noch einmal auszuwählen, oder eine Meldung mit einer Schaltfläche anzeigen, über die der Zugriff erneut autorisiert werden kann.

Anwendung identifizieren und Tasks API-Dienstobjekt einrichten

Nachdem Ihre Anwendung nun für den Zugriff auf die Tasks API autorisiert wurde und ein Zugriffstoken erhalten wurde, benötigen Sie außerdem einen API-Schlüssel, den Sie aus einem Projekt in der Google APIs-Konsole abrufen müssen, da er für Tasks API-Aufrufe obligatorisch ist. Führen Sie dazu die folgenden Schritte aus:

  1. Projekt erstellen oder vorhandenes verwenden
  2. Aktivieren Sie die Tasks API für Ihr Projekt, indem Sie den Schalter für die Tasks API auf AN stellen.
  3. Den API-Schlüssel finden Sie unter API-Zugriff > Einfacher API-Zugriff > API-Schlüssel.

API-Schlüssel über die APIs-Konsole abrufen
API-Schlüssel über die APIs-Konsole abrufen

Der API-Schlüssel ist obligatorisch, da er Ihre Anwendung identifiziert. Daher kann die API das Kontingent abziehen und die für Ihr Projekt definierten Kontingentregeln verwenden. Sie müssen den API-Schlüssel für das Tasks-Objekt service angeben:

useTasksAPI(String accessToken) {
  // Setting up the Tasks API Service
  HttpTransport transport = AndroidHttp.newCompatibleTransport();
  AccessProtectedResource accessProtectedResource = new GoogleAccessProtectedResource(accessToken);
  Tasks service = new Tasks(transport, accessProtectedResource, new JacksonFactory());
  service.accessKey = INSERT_YOUR_API_KEY;
  service.setApplicationName("Google-TasksSample/1.0");

  // TODO: now use the service to query the Tasks API
}

Das accessToken ist nur für einen bestimmten Zeitraum gültig, sodass Sie nach Ablauf ein neues anfordern müssen. Dafür gibt es zwei Möglichkeiten:

  • Fordern Sie bei jeder Anfrage über die API ein accessToken an den AccountManager an. Da der AccountManager das Token im Cache speichert, ist diese Lösung akzeptabel.
  • Verwenden Sie accessToken so lange, bis der Fehler 403 auftritt und Sie im AccountManager ein neues Token anfordern.

Aufgaben über die API bearbeiten

Sie sollten nun ein vollständig eingerichtetes Tasks API-Dienstobjekt haben, mit dem Sie die API gemäß dem Tasks API-Entwicklerhandbuch abfragen können. Beispiel:

// Getting all the Task lists
List taskLists = service.tasklists.list().execute().items;

// Getting the list of tasks in the default task list
List tasks = service.tasks.list("@default").execute().items;

// Add a task to the default task list
Task task = new Task();
task.title = "New Task";
task.notes = "Please complete me";
task.due = "2010-10-15T12:00:00.000Z";
Task result = service.tasks.insert("@default", task).execute();

Vergessen Sie nicht, Ihrem Android-Anwendungsmanifest die Berechtigung für den Internetzugriff hinzuzufügen, da die oben genannten Anfragen an die Tasks API-Endpunkte sonst fehlschlagen:

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

Beispielanwendung

Vor Kurzem haben wir dem Beispiel-Repository der Google APIs-Clientbibliothek für Java ein neues Beispiel hinzugefügt, das Ihnen den Einstieg in die Tasks API und OAuth 2.0 unter Android erleichtert. Das Beispiel ist eine einfache, aber voll funktionsfähige Android-Anwendung, die eine Autorisierung zur Verwendung der Tasks API anfordert und die Aufgaben der Standardaufgabenliste in einer ListView anzeigt.

Aufgaben in der Standardaufgabenliste in einer ListView anzeigen
Aufgaben in der Standardaufgabenliste in einer ListView anzeigen

Befolgen Sie diese instructions, um das Beispiel auszuführen. Zögern Sie nicht, Ihr Feedback oder Ihre Fragen im Google Tasks API-Forum zu posten.