如要透過 Google Play 服務 (例如 Google 登入或 ML Kit) 技術提供的 SDK 中的其中一個 API 呼叫，您必須先建立 API 用戶端物件的執行個體。這些物件會自動管理與 Google Play 服務的連線。如果有連線可用，每個 API 用戶端物件都會依序執行要求。否則，用戶端物件會將要求排入佇列。除非說明文件另有指示，否則用戶端物件建構成本很低；每次叫用 API 方法時，都可以建立新的 API 用戶端。
本指南說明如何向任何 Google Play 服務提供的 SDK 呼叫 API，包括如何存取不需要授權的服務，以及需要授權的服務。
立即開始
首先，請按照設定 Google Play 服務指南中的說明，在應用程式專案中新增必要的工具和依附元件。
在不需要授權時存取
如要存取不需要 API 授權的服務，請取得服務用戶端物件的執行個體，將目前的 Context 或目前的 Activity 傳遞至服務。執行任何 API 呼叫之前，系統會視情況提示使用者升級 Google Play 服務。
舉例來說，如要利用 Android 適用的整合式位置預測提供工具取得裝置的最後已知位置，請新增以下程式碼片段中的邏輯：
Kotlin
// Code required for requesting location permissions omitted for brevity. val client = LocationServices.getFusedLocationProviderClient(this) // Get the last known location. In some rare situations, this can be null. client.lastLocation.addOnSuccessListener { location : Location? -> location?.let { // Logic to handle location object. } }
Java
// Code required for requesting location permissions omitted for brevity. FusedLocationProviderClient client = LocationServices.getFusedLocationProviderClient(this); // Get the last known location. In some rare situations, this can be null. client.getLastLocation() .addOnSuccessListener(this, location -> { if (location != null) { // Logic to handle location object. } });
需要授權時存取
如要存取需要使用者授權的服務，請完成下列步驟：
- 讓使用者登入。
- 要求存取服務所需的範圍的權限。
- 取得服務用戶端物件的執行個體，除了
Context或Activity物件之外，也傳遞使用者的GoogleSignInAccount物件。
以下範例會使用 Google Fit API 讀取使用者的每日步數。如要在完整專案內容中查看類似的實作項目，請在 GitHub 上查看 BasicHistoryApiKotlin 應用程式的主要活動。
Kotlin
class FitFragment : Fragment() {
private val fitnessOptions: FitnessOptions by lazy {
FitnessOptions.builder()
.addDataType(DataType.TYPE_STEP_COUNT_CUMULATIVE)
.addDataType(DataType.TYPE_STEP_COUNT_DELTA)
.build()
}
override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
fitSignIn()
}
/*
* Checks whether the user is signed in. If so, executes the specified
* function. If the user is not signed in, initiates the sign-in flow,
* specifying the function to execute after the user signs in.
*/
private fun fitSignIn() {
if (oAuthPermissionsApproved()) {
readDailySteps()
} else {
GoogleSignIn.requestPermissions(
this,
SIGN_IN_REQUEST_CODE,
getGoogleAccount(),
fitnessOptions
)
}
}
private fun oAuthPermissionsApproved() =
GoogleSignIn.hasPermissions(getGoogleAccount(), fitnessOptions)
/*
* Gets a Google account for use in creating the fitness client. This is
* achieved by either using the last signed-in account, or if necessary,
* prompting the user to sign in. It's better to use the
* getAccountForExtension() method instead of the getLastSignedInAccount()
* method because the latter can return null if there has been no sign in
* before.
*/
private fun getGoogleAccount(): GoogleSignInAccount =
GoogleSignIn.getAccountForExtension(requireContext(), fitnessOptions)
/*
* Handles the callback from the OAuth sign in flow, executing the function
* after sign-in is complete.
*/
override fun onActivityResult(
requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)
when (resultCode) {
RESULT_OK -> {
readDailySteps()
}
else -> {
// Handle error.
}
}
}
/*
* Reads the current daily step total.
*/
private fun readDailySteps() {
Fitness.getHistoryClient(requireContext(), getGoogleAccount())
.readDailyTotal(DataType.TYPE_STEP_COUNT_DELTA)
.addOnSuccessListener { dataSet ->
val total = when {
dataSet.isEmpty -> 0
else -> dataSet.dataPoints.first()
.getValue(Field.FIELD_STEPS).asInt()
}
Log.i(TAG, "Total steps: $total")
}
.addOnFailureListener { e ->
Log.w(TAG, "There was a problem getting the step count.", e)
}
}
companion object {
const val SIGN_IN_REQUEST_CODE = 1001
}
}
Java
public class FitFragment extends Fragment {
private final FitnessOptions fitnessOptions = FitnessOptions.builder()
.addDataType(DataType.TYPE_STEP_COUNT_CUMULATIVE)
.addDataType(DataType.TYPE_STEP_COUNT_DELTA)
.build();
@Override
public void onViewCreated(
@NotNull View view, @Nullable Bundle savedInstanceState) {
fitSignIn();
}
/*
* Checks whether the user is signed in. If so, executes the specified
* function. If the user is not signed in, initiates the sign-in flow,
* specifying the function to execute after the user signs in.
*/
private void fitSignIn() {
if (oAuthPermissionsApproved()) {
readDailySteps();
} else {
GoogleSignIn.requestPermissions(this, SIGN_IN_REQUEST_CODE,
getGoogleAccount(), fitnessOptions);
}
}
private boolean oAuthPermissionsApproved() {
return GoogleSignIn.hasPermissions(getGoogleAccount(), fitnessOptions);
}
/*
* Gets a Google account for use in creating the fitness client. This is
* achieved by either using the last signed-in account, or if necessary,
* prompting the user to sign in. It's better to use the
* getAccountForExtension() method instead of the getLastSignedInAccount()
* method because the latter can return null if there has been no sign in
* before.
*/
private GoogleSignInAccount getGoogleAccount() {
return GoogleSignIn.getAccountForExtension(
requireContext(), fitnessOptions);
}
/*
* Handles the callback from the OAuth sign in flow, executing the function
* after sign-in is complete.
*/
@Override
public void onActivityResult(
int requestCode, int resultCode, @Nullable Intent data) {
super.onActivityResult(requestCode, resultCode, data);
if (resultCode == RESULT_OK) {
readDailySteps();
} else {
// Handle error.
}
}
/*
* Reads the current daily step total.
*/
private void readDailySteps() {
AtomicInteger total = new AtomicInteger();
Fitness.getHistoryClient(requireContext(), getGoogleAccount())
.readDailyTotal(DataType.TYPE_STEP_COUNT_DELTA)
.addOnSuccessListener(dataSet -> {
if (!dataSet.isEmpty())
total.set(Integer.parseInt(dataSet.getDataPoints()
.get(0).getValue(FIELD_STEPS).toString()));
Log.i(TAG, "Total steps: $total");
})
.addOnFailureListener(e -> {
Log.w(TAG, "There was a problem getting the step count.", e);
});
}
private static final int SIGN_IN_REQUEST_CODE = 1001;
}
檢查 API 可用性
在應用程式中啟用需要 Google Play 服務 API 的功能之前，請先檢查裝置是否可使用這個 API。如要延長，請呼叫 checkApiAvailability()。
下列程式碼片段說明如何檢查整合式位置預測提供工具的可用性。
Kotlin
fun getLastLocationIfApiAvailable(context: Context?): Task<Location>? {
val client = getFusedLocationProviderClient(context)
return GoogleApiAvailability.getInstance()
.checkApiAvailability(client)
.onSuccessTask { _ -> client.lastLocation }
.addOnFailureListener { _ -> Log.d(TAG, "Location unavailable.")}
}
Java
public Task<Location> getLastLocationIfApiAvailable(Context context) {
FusedLocationProviderClient client =
getFusedLocationProviderClient(context);
return GoogleApiAvailability.getInstance()
.checkApiAvailability(client)
.onSuccessTask(unused -> client.getLastLocation())
.addOnFailureListener(e -> Log.d(TAG, "Location unavailable."));
}