الوصول إلى Google APIs

عندما تريد إجراء طلب إلى إحدى واجهات برمجة التطبيقات في حِزمة تطوير برامج (SDK) مدعومة من خدمات Google Play، مثل Google Sign-in أو ML Kit، عليك أولاً إنشاء مثيل لعنصر عميل واجهة برمجة التطبيقات. تدير هذه العناصر تلقائيًا الاتصال بـ "خدمات Google Play". عندما يكون الاتصال متاحًا، ينفِّذ كل عنصر عميل لواجهة برمجة التطبيقات الطلبات بالترتيب. بخلاف ذلك، يضع عنصر العميل الطلبات في قائمة الانتظار. ما لم تشير الوثائق إلى خلاف ذلك، يمكن إنشاء مثيلات عملاء بتكلفة منخفضة، ولا بأس من إنشاء عملاء جدد لواجهات برمجة التطبيقات في كل مرة تريد فيها تنفيذ مثيلات واجهة برمجة التطبيقات.

يوضّح هذا الدليل كيفية إجراء طلبات بيانات من واجهة برمجة التطبيقات إلى أيّ من حِزم تطوير البرامج (SDK) التي تعمل باستخدام "خدمات Google Play"، بما في ذلك كيفية الوصول إلى الخدمات التي لا تحتاج إلى تفويض وتلك التي تتطلّب تفويضًا.

البدء

للبدء، أضِف الأدوات والتبعيات اللازمة في مشروع تطبيقك، كما هو описан في الدليل حول كيفية إعداد خدمات Google Play.

الوصول عندما لا يكون التفويض مطلوبًا

للوصول إلى خدمة لا تتطلّب إذنًا لواجهة برمجة التطبيقات، احصل على مثيل لعنصر عميل الخدمة، مع تمريره إما بالقيمة الحالية Context أو القيمة الحالية Activity. قبل تنفيذ أي طلبات من واجهة برمجة التطبيقات، يُطلَب من المستخدمين ترقية خدمات Google Play إذا لزم الأمر.

على سبيل المثال، للحصول على آخر موقع جغرافي معروف للجهاز باستخدام Fused Location Provider لنظام التشغيل 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;
}

التحقّق من توفّر واجهة برمجة التطبيقات

قبل تفعيل ميزة في تطبيقك تعتمد على واجهة برمجة تطبيقات "خدمات Google Play"، يجب تضمين عملية تحقّق من توفّر واجهة برمجة التطبيقات على الجهاز. لإجراء ذلك، اتصل على 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."));
}