GoogleApiClient（「Google API クライアント」）オブジェクトを使用すると、Google Play 開発者サービス ライブラリで提供される Google API（Google ログイン、ゲーム、ドライブなど）にアクセスできます。Google API クライアントは、Google Play 開発者サービスへの共通のエントリ ポイントを提供し、ユーザーのデバイスと各 Google サービス間のネットワーク接続を管理します。
ただし、新しい GoogleApi インターフェースとその実装の方が使いやすく、Play 開発者サービス API にアクセスする方法として推奨されています。Google API へのアクセスをご覧ください。
このガイドでは、次の方法について説明します。
- Google Play 開発者サービスへの接続を自動的に管理します。
- いずれかの Google Play 開発者サービスに対して同期および非同期の API 呼び出しを実行します。
- まれに必要になる場合は、Google Play 開発者サービスへの接続を手動で管理します。詳細については、手動で管理される接続をご覧ください。
まず、Android SDK 用の Google Play 開発者サービス ライブラリ（リビジョン 15 以降）をインストールする必要があります。まだ行っていない場合は、Google Play 開発者サービス SDK をセットアップするの手順を行ってください。
自動管理接続を開始する
プロジェクトを Google Play 開発者サービス ライブラリにリンクしたら、アクティビティの onCreate() メソッドで GoogleApiClient.Builder API を使用して、GoogleApiClient のインスタンスを作成します。GoogleApiClient.Builder クラスには、使用する Google API と必要な OAuth 2.0 スコープを指定できるメソッドが用意されています。Google ドライブ サービスに接続する GoogleApiClient インスタンスを作成するコードの例を次に示します。
GoogleApiClient mGoogleApiClient = new GoogleApiClient.Builder(this)
.enableAutoManage(this /* FragmentActivity */,
this /* OnConnectionFailedListener */)
.addApi(Drive.API)
.addScope(Drive.SCOPE_FILE)
.build();
addApi() と addScope() の呼び出しを追加することで、複数の API と複数のスコープを同じ GoogleApiClient に追加できます。
重要: Wearable API を他の API と一緒に GoogleApiClient に追加すると、Wear OS アプリがインストールされていないデバイスでクライアント接続エラーが発生する可能性があります。接続エラーを回避するには、addApiIfAvailable() メソッドを呼び出して Wearable API を渡し、不足している API をクライアントが適切に処理できるようにします。詳しくは、Wearable API にアクセスするをご覧ください。
自動管理接続を開始するには、解決できない接続エラーを受け取るように OnConnectionFailedListener インターフェースの実装を指定する必要があります。自動管理の GoogleApiClient インスタンスが Google API に接続しようとすると、解決可能な接続エラー（Google Play 開発者サービスの更新が必要な場合など）の修正を試みる UI が自動的に表示されます。解決できないエラーが発生した場合は、onConnectionFailed() が呼び出されます。
自動管理される接続が確立または一時停止されるタイミングをアプリが認識する必要がある場合は、ConnectionCallbacks インターフェースのオプションの実装を指定することもできます。たとえば、アプリが Google API にデータを書き込む呼び出しを行う場合、これらは onConnected() メソッドが呼び出された後にのみ呼び出す必要があります。
次に、コールバック インターフェースを実装して Google API クライアントに追加するアクティビティの例を示します。
import com.google.android.gms.common.api.GoogleApiClient;
import com.google.android.gms.common.api.GoogleApiClient.OnConnectionFailedListener;
import gms.drive.*;
import android.support.v4.app.FragmentActivity;
public class MyActivity extends FragmentActivity
implements OnConnectionFailedListener {
private GoogleApiClient mGoogleApiClient;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Create a GoogleApiClient instance
mGoogleApiClient = new GoogleApiClient.Builder(this)
.enableAutoManage(this /* FragmentActivity */,
this /* OnConnectionFailedListener */)
.addApi(Drive.API)
.addScope(Drive.SCOPE_FILE)
.build();
// ...
}
@Override
public void onConnectionFailed(ConnectionResult result) {
// An unresolvable error has occurred and a connection to Google APIs
// could not be established. Display an error message, or handle
// the failure silently
// ...
}
}
GoogleApiClient インスタンスは、アクティビティが onStart() を呼び出した後に自動的に接続され、onStop() を呼び出した後に切断されます。アプリは、GoogleApiClient をビルドすると、接続の完了を待たずに Google API への読み取りリクエストをすぐに開始できます。
Google サービスと通信する
接続後、クライアントは、GoogleApiClient インスタンスに追加した API とスコープの指定に従って、アプリが承認されているサービス固有の API を使用して、読み取りと書き込みの呼び出しを行うことができます。
注: 特定の Google サービスを呼び出す前に、Google Developer Console でアプリを登録する必要があります。手順については、使用している API のスタートガイド（Google ドライブや Google ログインなど）をご覧ください。
GoogleApiClient を使用して読み取りまたは書き込みリクエストを実行すると、API クライアントはリクエストを表す PendingResult オブジェクトを返します。この処理は、アプリが呼び出している Google サービスにリクエストが配信される直前に行われます。
たとえば、次のリクエストでは、PendingResult オブジェクトを含むファイルを Google ドライブから読み取ることができます。
Query query = new Query.Builder()
.addFilter(Filters.eq(SearchableField.TITLE, filename));
PendingResult<DriveApi.MetadataBufferResult> result = Drive.DriveApi.query(mGoogleApiClient, query);
アプリに PendingResult オブジェクトを設定すると、リクエストを非同期呼び出しとして処理するか、同期呼び出しとして処理するかを指定できます。
ヒント: アプリは、Google Play 開発者サービスに接続していないときに読み取りリクエストをキューに追加できます。たとえば、GoogleApiClient インスタンスがまだ接続されているかどうかにかかわらず、アプリは Google ドライブからファイルを読み取るメソッドを呼び出すことができます。接続が確立されると、キューに登録された読み取りリクエストが実行されます。Google API クライアントが接続されていないときに、アプリが Google Play 開発者サービスの書き込みメソッドを呼び出すと、書き込みリクエストによってエラーが発生します。
非同期呼び出しの使用
リクエストを非同期にするには、PendingResult で setResultCallback() を呼び出し、ResultCallback インターフェースの実装を提供します。非同期的に実行されたリクエストの例を次に示します。
private void loadFile(String filename) {
// Create a query for a specific filename in Drive.
Query query = new Query.Builder()
.addFilter(Filters.eq(SearchableField.TITLE, filename))
.build();
// Invoke the query asynchronously with a callback method
Drive.DriveApi.query(mGoogleApiClient, query)
.setResultCallback(new ResultCallback<DriveApi.MetadataBufferResult>() {
@Override
public void onResult(DriveApi.MetadataBufferResult result) {
// Success! Handle the query result.
// ...
}
});
}
アプリが onResult() コールバックで Result オブジェクトを受け取ると、使用している API で指定されている適切なサブクラス（DriveApi.MetadataBufferResult など）のインスタンスとして配信されます。
同期呼び出しの使用
厳密に定義された順序でコードを実行する場合（ある呼び出しの結果が別の呼び出しの引数として必要になる場合など）は、PendingResult に対して await() を呼び出すことで、リクエストを同期させることができます。これによりスレッドがブロックされ、リクエストが完了すると Result オブジェクトが返されます。このオブジェクトは、使用している API（DriveApi.MetadataBufferResult など）で指定されている適切なサブクラスのインスタンスとして提供されます。
await() を呼び出すと、結果が届くまでスレッドがブロックされるため、UI スレッドでは Google API に同期リクエストを行ってはなりません。アプリで AsyncTask オブジェクトを使用して新しいスレッドを作成し、そのスレッドを使用して同期リクエストを行うことができます。
次の例は、Google ドライブへのファイル リクエストを同期呼び出しとして行う方法を示しています。
private void loadFile(String filename) {
new GetFileTask().execute(filename);
}
private class GetFileTask extends AsyncTask {
protected void doInBackground(String filename) {
Query query = new Query.Builder()
.addFilter(Filters.eq(SearchableField.TITLE, filename))
.build();
// Invoke the query synchronously
DriveApi.MetadataBufferResult result =
Drive.DriveApi.query(mGoogleApiClient, query).await();
// Continue doing other stuff synchronously
// ...
}
}
Wearable API にアクセスする
Wearable API は、ハンドヘルド デバイスとウェアラブル デバイスで動作するアプリ用の通信チャネルを提供します。この API は、システムが送信して同期できる一連のデータ オブジェクトと、データレイヤーを使用して重要なイベントをアプリに通知するリスナーで構成されます。Wearable API は、Android 4.3（API レベル 18）以降を搭載したデバイスでウェアラブル デバイスが接続され、Wear OS コンパニオン アプリがインストールされている場合に利用できます。
Wearable API をスタンドアロンで使用する
アプリで Wearable API を使用していて、他の Google API を使用していない場合、addApi() メソッドを呼び出してこの API を追加できます。次の例は、Wearable API を GoogleApiClient インスタンスに追加する方法を示しています。
GoogleApiClient mGoogleApiClient = new GoogleApiClient.Builder(this)
.enableAutoManage(this /* FragmentActivity */,
this /* OnConnectionFailedListener */)
.addApi(Wearable.API)
.build();
Wearable API を使用できない場合、Wearable API を含む接続リクエストは失敗し、API_UNAVAILABLE エラーコードが返されます。
次の例は、Wearable API が使用可能かどうかを判断する方法を示しています。
// Connection failed listener method for a client that only
// requests access to the Wearable API
@Override
public void onConnectionFailed(ConnectionResult result) {
if (result.getErrorCode() == ConnectionResult.API_UNAVAILABLE) {
// The Wearable API is unavailable
}
// ...
}
Wearable API と他の Google API の使用
アプリで他の Google API に加えて Wearable API を使用している場合は、addApiIfAvailable() メソッドを呼び出して Wearable API を渡し、使用可能かどうかを確認します。このチェックを使用すると、API を使用できないケースを適切に処理できます。
次の例は、Drive API とともに Wearable API にアクセスする方法を示しています。
// Create a GoogleApiClient instance
mGoogleApiClient = new GoogleApiClient.Builder(this)
.enableAutoManage(this /* FragmentActivity */,
this /* OnConnectionFailedListener */)
.addApi(Drive.API)
.addApiIfAvailable(Wearable.API)
.addScope(Drive.SCOPE_FILE)
.build();
上記の例では、Wearable API が使用できない場合、GoogleApiClient は Wearable API に接続しなくても、Google ドライブに正常に接続できます。GoogleApiClient インスタンスを接続したら、API 呼び出しを行う前に、Wearable API が使用可能であることを確認します。
boolean wearAvailable = mGoogleApiClient.hasConnectedApi(Wearable.API);
API 接続エラーを無視する
addApi() を呼び出し、GoogleApiClient がその API に正常に接続できない場合、そのクライアントの接続オペレーション全体が失敗し、onConnectionFailed() コールバックがトリガーされます。
API 接続エラーを無視するには、addApiIfAvailable() を使用します。addApiIfAvailable() で追加した API が修復不可能なエラー（Wear の API_UNAVAILABLE など）で接続に失敗した場合、その API は GoogleApiClient から削除され、クライアントは他の API への接続に進みます。ただし、復元可能なエラー（OAuth 同意解決インテントなど）で API 接続が失敗した場合、クライアントの接続オペレーションは失敗します。自動管理接続を使用している場合、GoogleApiClient は可能な限りこのようなエラーの解決を試みます。手動で管理する接続を使用すると、解決インテントを含む ConnectionResult が onConnectionFailed() コールバックに送られます。API 接続の失敗は、障害の解決策がなく、addApiIfAvailable() で API が追加された場合にのみ無視されます。手動での接続障害処理を実装する方法については、接続障害を処理するをご覧ください。
addApiIfAvailable() で追加された API は、接続された GoogleApiClient インスタンスに常に存在するとは限らないため、hasConnectedApi() を使用してチェックを追加することで、これらの API の呼び出しを保護する必要があります。クライアントに対する接続オペレーション全体が成功したときに、特定の API が接続に失敗した理由を調べるには、getConnectionResult() を呼び出して、ConnectionResult オブジェクトからエラーコードを取得します。クライアントに接続されていないときにクライアントが API を呼び出すと、呼び出しは API_NOT_AVAILABLE ステータス コードで失敗します。
addApiIfAvailable() で追加する API に 1 つ以上のスコープが必要な場合は、addScope() メソッドを使用するのではなく、それらのスコープを addApiIfAvailable() メソッド呼び出しのパラメータとして追加します。OAuth 同意を取得する前に API 接続が失敗した場合、この方法で追加されたスコープはリクエストされませんが、addScope() で追加されたスコープは常にリクエストされます。
手動で管理される接続
このガイドの大部分では、enableAutoManage メソッドを使用して、エラーが自動的に解決された自動管理接続を開始する方法について説明します。ほぼすべてのケースで、これが Android アプリから Google API に接続する最善かつ最も簡単な方法です。ただし、アプリで Google API への接続を手動で管理したほうがよい場合もあります。
- アクティビティの外部で Google API にアクセスする場合、または API 接続の制御を維持する場合
- 接続エラーの処理と解決をカスタマイズするには
このセクションでは、これらのユースケースとその他の高度なユースケースの例を示します。
手動で管理する接続を開始する
GoogleApiClient への手動で管理される接続を開始するには、コールバック インターフェース（ConnectionCallbacks および OnConnectionFailedListener）の実装を指定する必要があります。これらのインターフェースは、Google Play 開発者サービスへの接続が成功、失敗、または停止されたときに、非同期の connect() メソッドへのレスポンスとしてコールバックを受け取ります。
mGoogleApiClient = new GoogleApiClient.Builder(this)
.addApi(Drive.API)
.addScope(Drive.SCOPE_FILE)
.addConnectionCallbacks(this)
.addOnConnectionFailedListener(this)
.build()
接続を手動で管理する場合は、アプリのライフサイクルの適切なタイミングで connect() メソッドと disconnect() メソッドを呼び出す必要があります。アクティビティのコンテキストでは、アクティビティの onStart() メソッドで connect() を呼び出し、アクティビティの onStop() メソッドで disconnect() を呼び出すことをおすすめします。connect() メソッドと disconnect() メソッドは、自動管理接続を使用すると自動的に呼び出されます。
GoogleApiClient を使用して Google ドライブや Google Play Games などの認証が必要な API に接続する場合、最初の接続試行が失敗し、ユーザー アカウントが指定されていないため、アプリが onConnectionFailed() の呼び出しを SIGN_IN_REQUIRED エラーで受け取る可能性があります。
接続エラーを処理する
アプリが onConnectionFailed() コールバックへの呼び出しを受け取った場合は、指定された ConnectionResult オブジェクトで hasResolution() を呼び出す必要があります。true が返された場合、アプリは ConnectionResult オブジェクトの startResolutionForResult() を呼び出すことで、エラーを解決するための迅速なアクションをユーザーに要求できます。この場合、startResolutionForResult() メソッドは startActivityForResult() と同じように動作し、ユーザーがエラーを解決できるようにするコンテキストに適したアクティビティ（ユーザーがアカウントを選択できるようにするアクティビティなど）を起動します。
hasResolution() が false を返した場合、アプリは GoogleApiAvailability.getErrorDialog() を呼び出して、エラーコードをこのメソッドに渡す必要があります。これにより、エラーに適した Google Play 開発者サービス提供の Dialog が返されます。ダイアログでは、単にエラーを説明するメッセージを表示するだけの場合もあれば、エラーを解決できるアクティビティを起動するアクション（ユーザーが新しいバージョンの Google Play 開発者サービスをインストールする必要がある場合など）を提供する場合もあります。
たとえば、onConnectionFailed() コールバック メソッドは次のようになります。
public class MyActivity extends Activity
implements ConnectionCallbacks, OnConnectionFailedListener {
// Request code to use when launching the resolution activity
private static final int REQUEST_RESOLVE_ERROR = 1001;
// Unique tag for the error dialog fragment
private static final String DIALOG_ERROR = "dialog_error";
// Bool to track whether the app is already resolving an error
private boolean mResolvingError = false;
// ...
@Override
public void onConnectionFailed(ConnectionResult result) {
if (mResolvingError) {
// Already attempting to resolve an error.
return;
} else if (result.hasResolution()) {
try {
mResolvingError = true;
result.startResolutionForResult(this, REQUEST_RESOLVE_ERROR);
} catch (SendIntentException e) {
// There was an error with the resolution intent. Try again.
mGoogleApiClient.connect();
}
} else {
// Show dialog using GoogleApiAvailability.getErrorDialog()
showErrorDialog(result.getErrorCode());
mResolvingError = true;
}
}
// The rest of this code is all about building the error dialog
/* Creates a dialog for an error message */
private void showErrorDialog(int errorCode) {
// Create a fragment for the error dialog
ErrorDialogFragment dialogFragment = new ErrorDialogFragment();
// Pass the error that should be displayed
Bundle args = new Bundle();
args.putInt(DIALOG_ERROR, errorCode);
dialogFragment.setArguments(args);
dialogFragment.show(getSupportFragmentManager(), "errordialog");
}
/* Called from ErrorDialogFragment when the dialog is dismissed. */
public void onDialogDismissed() {
mResolvingError = false;
}
/* A fragment to display an error dialog */
public static class ErrorDialogFragment extends DialogFragment {
public ErrorDialogFragment() { }
@Override
public Dialog onCreateDialog(Bundle savedInstanceState) {
// Get the error code and retrieve the appropriate dialog
int errorCode = this.getArguments().getInt(DIALOG_ERROR);
return GoogleApiAvailability.getInstance().getErrorDialog(
this.getActivity(), errorCode, REQUEST_RESOLVE_ERROR);
}
@Override
public void onDismiss(DialogInterface dialog) {
((MyActivity) getActivity()).onDialogDismissed();
}
}
}
ユーザーが startResolutionForResult() によって提供されたダイアログを完了するか、GoogleApiAvailability.getErrorDialog() によって提供されたメッセージを閉じると、アクティビティは RESULT_OK 結果コードを使用して onActivityResult() コールバックを受け取ります。その後、アプリは connect() を再度呼び出すことができます。次に例を示します。
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == REQUEST_RESOLVE_ERROR) {
mResolvingError = false;
if (resultCode == RESULT_OK) {
// Make sure the app is not already connected or attempting to connect
if (!mGoogleApiClient.isConnecting() &&
!mGoogleApiClient.isConnected()) {
mGoogleApiClient.connect();
}
}
}
}
上記のコードでは、ブール値 mResolvingError に気付かれたと思います。これにより、ユーザーがエラーを解決している間にアプリの状態が追跡され、同じエラーの解決を繰り返し試みることがなくなります。たとえば、SIGN_IN_REQUIRED エラーの解決に役立つアカウント選択ダイアログが表示されている間、ユーザーが画面を回転させることがあります。これによりアクティビティが再作成され、onStart() メソッドが再度呼び出され、さらに connect() が再度呼び出されます。これにより、startResolutionForResult() がもう一度呼び出され、既存のアカウントの前に別のアカウント選択ダイアログが作成されます。
このブール値は、アクティビティ インスタンス間で維持される場合にのみ、本来の目的を果たします。 次のセクションでは、他のユーザー アクションやデバイスで発生するイベントに関係なく、アプリのエラー処理の状態を維持する方法について説明します。
エラーの解決中に状態を維持する
以前のエラー解決の進行中に onConnectionFailed() のコードを実行しないようにするには、アプリがすでにエラー解決を試行しているかどうかを追跡するブール値を保持する必要があります。
上のコードサンプルに示すように、アプリは startResolutionForResult() を呼び出すたびに、または GoogleApiAvailability.getErrorDialog() からダイアログを表示するたびに、ブール値を true に設定する必要があります。次に、アプリが onActivityResult() コールバックで RESULT_OK を受け取ったら、ブール値を false に設定します。
アクティビティの再起動後（ユーザーが画面を回転したときなど）にブール値を追跡するには、onSaveInstanceState() を使用して、アクティビティの保存済みインスタンス データにブール値を保存します。
private static final String STATE_RESOLVING_ERROR = "resolving_error";
@Override
protected void onSaveInstanceState(Bundle outState) {
super.onSaveInstanceState(outState);
outState.putBoolean(STATE_RESOLVING_ERROR, mResolvingError);
}
次に、onCreate() で保存済み状態を復元します。
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// ...
mResolvingError = savedInstanceState != null
&& savedInstanceState.getBoolean(STATE_RESOLVING_ERROR, false);
}
これで、アプリを安全に実行し、Google Play 開発者サービスに手動で接続できるようになりました。