גישה ל-Google APIs

אם רוצים לבצע קריאה לאחד מממשקי ה-API ב-SDK שמופעל על ידי Google Play Services, כמו כניסה באמצעות Google או ML Kit, קודם צריך ליצור מכונה של אובייקט לקוח ב-API. האובייקטים האלה מנהלים באופן אוטומטי את החיבור אל Google Play Services. כשיש חיבור זמין, כל אובייקט לקוח ב-API מבצע בקשות לפי הסדר. אחרת, אובייקט הלקוח מכניס את הבקשות לתור. אלא אם התיעוד מציין אחרת, אובייקטים של לקוח הם זולים לבנייה. מותר ליצור לקוחות API חדשים בכל פעם שרוצים להפעיל שיטות API.

במדריך הזה מוסבר איך לבצע קריאות ל-API לכל אחת מערכות ה-SDK שמופעלות על ידי Google Play Services, כולל איך ניגשים לשירותים שלא דורשים הרשאה ולכאלה שמחייבים הרשאה.

תחילת העבודה

כדי להתחיל, צריך להוסיף את יחסי התלות והכלים הנדרשים לפרויקט האפליקציה, כמו שמתואר במדריך להגדרת Google Play Services.

גישה כשלא נדרשת הרשאה

כדי לגשת לשירות שלא מחייב הרשאת API, מקבלים מכונה של אובייקט הלקוח של השירות ומעבירים אותו לערך Context הנוכחי או ל-Activity הנוכחי. לפני הרצת הקריאות ל-API, המשתמשים מתבקשים לשדרג את שירותי Google Play במידת הצורך.

לדוגמה, כדי לקבל את המיקום הידוע האחרון של המכשיר באמצעות Fused LocationProvider עבור 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.
            }
        });

גישה כשנדרשת הרשאה

על מנת לגשת לשירות שדורש הרשאת משתמש:

  1. מכניסים את המשתמש לחשבון.
  2. מבקשים הרשאה לגשת להיקפי ההרשאות שהשירות דורש.
  3. מקבלים מכונה של אובייקט הלקוח של השירות ומעבירים את האובייקט GoogleSignInAccount של המשתמש, בנוסף לאובייקט Context או Activity של המשתמש.

בדוגמה הבאה אפשר לקרוא את הצעדים היומיים של המשתמש באמצעות Google Fit API. כדי לראות הטמעה דומה בהקשר של פרויקט מלא, תוכלו לקרוא את הפעילות העיקרית של האפליקציה BasicHistoryApiKotlin ב-GitHub.

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

לפני שמפעילים באפליקציה תכונה שתלויה ב-API של Google Play Services, חשוב לבדוק את הזמינות של ה-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."));
}