الوصول إلى Google APIs

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

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

البدء

للبدء، أضف الأدوات والتبعيات اللازمة في مشروع تطبيقك، كما هو موضح في الدليل حول كيفية إعداد Google Play .

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

للوصول إلى خدمة لا تتطلب تفويض واجهة برمجة التطبيقات، احصل على مثال كائن عميل الخدمة، مع تمريره إما العنصر الحالي Context أو الحالي Activity يُطلب من المستخدمين ترقية 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.
            }
        });

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

للوصول إلى خدمة تتطلب تفويض المستخدم، عليك إكمال ما يلي: الخطوات:

1. سجِّل دخول المستخدم.
2. اطلب إذن الوصول إلى النطاقات التي تتطلّبها الخدمة.
3. الحصول على مثيل لكائن عميل الخدمة، وتمريره إلى كائن المستخدم GoogleSignInAccount كائن بالإضافة إلى Context أو Activity الخاص بك.

ينفذ المثال التالي قراءة الخطوات اليومية للمستخدم باستخدام الجدول Fit API لعرض تنفيذ مماثل في سياق مشروع كامل، عرض النشاط الرئيسي 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;
}

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

قبل تفعيل ميزة في تطبيقك تعتمد على "خدمات 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."));
}