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();
複数の API と複数のスコープを同じ GoogleApiClient に追加するには、addApi() と addScope() に対する呼び出しを追加します。
重要: 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 でアプリを登録する必要があります。手順については、Google ドライブや Google ログインなど、使用している API のスタートガイドをご覧ください。
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 開発者サービスの write メソッドを呼び出すと、書き込みリクエストでエラーが発生します。
非同期呼び出しの使用
リクエストを非同期にするには、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 は Google ドライブに正常に接続できます。GoogleApiClient インスタンスを接続したら、API 呼び出しを行う前に、Wearable API を使用できることを確認します。
boolean wearAvailable = mGoogleApiClient.hasConnectedApi(Wearable.API);
API 接続エラーの無視
addApi() を呼び出し、GoogleApiClient がその API に正常に接続できない場合、そのクライアントの接続オペレーション全体で失敗し、onConnectionFailed() コールバックがトリガーされます。
addApiIfAvailable() を使用すると、無視するように API 接続の失敗を登録できます。addApiIfAvailable() で追加された API が回復不能なエラー（Wear の API_UNAVAILABLE など）によって接続に失敗した場合、その API は GoogleApiClient から削除され、クライアントは他の API への接続に進みます。ただし、API 接続が回復可能なエラー（OAuth 同意解決インテントなど）で失敗した場合、クライアント接続オペレーションは失敗します。自動管理接続を使用している場合、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 開発者サービスに手動で接続する準備が整いました。