如果您想调用由 Google Play 服务（如 Google 登录或机器学习套件）提供支持的 SDK 中的其中一个 API，则需要先创建 API 客户端对象实例。这些对象会自动管理与 Google Play 服务的连接。连接可用后，每个 API 客户端对象都会按顺序执行请求。否则，客户端对象会将请求加入队列。除非文档另有说明，否则客户端对象构建成本低廉；每次想要调用 API 方法时，都可以创建新的 API 客户端。
本指南介绍了如何对由 Google Play 服务提供支持的任何 SDK 进行 API 调用，包括如何访问不需要授权的服务和需要授权的 SDK。
开始使用
如需开始操作，请按照有关如何设置 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. } });
需要授权时访问
如需访问需要用户授权的服务，请完成以下步骤：
- 让用户登录。
- 请求访问服务所需的范围的权限。
- 获取服务的客户端对象实例，并向其传递用户的
GoogleSignInAccount对象以及Context或Activity对象。
以下示例展示了如何使用 Google Fit API 读取用户的每日步数。如需在完整项目的上下文中查看类似的实现，请在 GitHub 上查看 BasicHistoryApiKotlin 主 activity。
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 Services 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."));
}