العمليات الشائعة

تقدم هذه الصفحة أمثلة لبعض العمليات الشائعة التي قد تجريها في "مكتبة مورِّد Android المشتركة"، بما في ذلك:

إنشاء كائنات ResellerService

يمكنك استخدام فئتيّ المصنع من Samsung وGoogle لإنشاء كائنات ResellerService. باستخدام كائنات ResellerService، تتوفّر مجموعة من الطرق الشائعة لتسجيل أجهزة Samsung وغيرها من أجهزة Android.

أجهزة Samsung

يوضّح المثال أدناه كيفية إنشاء كائن ResellerService باستخدام الصف SamsungResellerServiceFactory لإدارة أجهزة Samsung.

وحتى تتمكّن من تنفيذ ذلك، عليك الاشتراك مع Knox Deployment Program (KDP).

ResellerService samsungResellerService = SamsungResellerServiceFactory.createResellerService(resellerId, serviceAccountKeyFilePath, clientIdentifier);

الأجهزة الأخرى التي تعمل بنظام التشغيل Android

يوضّح المثال أدناه كيفية إنشاء كائن ResellerService باستخدام الصف GoogleResellerServiceFactory لإدارة أجهزة Android الأخرى (بخلاف Samsung). قبل اتّخاذ هذا الإجراء، عليك اتّباع الخطوات الواردة في بدء استخدام برنامج "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة" للحصول على resellerId ومفتاح حساب الخدمة.

ResellerService googleResellerService = GoogleResellerServiceFactory.createResellerService(resellerId, serviceAccountKeyFilePath);

إنشاء كائنات Customer

ويتطلب العميل الذي يشتري أجهزة Samsung وغيرها من الأجهزة رقمَين تعريفيَين للعميل.

أجهزة Samsung

لإدارة أجهزة Samsung، يمكنك استخدام الرقم التعريفي لعميل Knox للعميل. للحصول على الرقم التعريفي لعميل Knox، يجب أولاً إنشاء كائن Customer. لإجراء ذلك، اتصل برقم createCustomer باستخدام SamsungResellerService التي تم إنشاؤها من SamsungResellerServiceFactory. وفي ما يلي مثال لذلك:

CreateCustomerRequest request = CreateCustomerRequest.newBuilder()
    .setCustomerName("TestCustomer") .addPrimaryEmails("superAdmin@gmail.com")
    .putVendorParams("country", "US") .putVendorParams("firstName", "Avery")
    .putVendorParams("lastName", "Yamada") .putVendorParams("service", "KME")
    .build();
CreateCustomerResponse response = samsungResellerService.createCustomer(request);
String companyId = response.getCustomer().getCompanyReference().getCompanyId();

في حالة نجاح هذا الطلب، يتم إرجاع كائن CreateCustomerResponse يمكنك من خلاله استخراج الرقم التعريفي لعميل Knox.

الأجهزة الأخرى التي تعمل بنظام التشغيل Android

أما بالنسبة إلى الأجهزة الأخرى التي تعمل بنظام التشغيل Android، فإن العميل يحتاج إلى رقم تعريفي لعميل "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة". إذا كان العميل يستخدم "إعداد الأجهزة الجوّالة للمؤسّسات دفعةً واحدة" مع مورِّد آخر، يمكنك استخدام الرقم التعريفي الحالي للعميل. وبخلاف ذلك، عليك إنشاء كائن Customer. لإجراء ذلك، يمكنك الاتصال بـ createCustomer باستخدام ResellerService من GoogleResellerServiceFactory. وفي ما يلي مثال على ذلك:

CreateCustomerRequest request = CreateCustomerRequest.newBuilder()
    .setCustomerName("TestCustomer")
    .addPrimaryEmails("owner@gmail.com")
    .addSecondaryEmails("admin@gmail.com")
    .build();
CreateCustomerResponse response = googleResellerService.createCustomer(request);
String companyId = response.getCustomer().getCompanyReference().getCompanyId();

وفي حال نجاح هذا الإجراء، يعرض الطلب كائن CreateCustomerResponse. يمكنك استرداد الرقم التعريفي للعميل من الرد.

المطالبة بمجموعة من الأجهزة

تؤدي المطالبة بجهاز إلى إنشاء رابط بين الجهاز والعميل. على سبيل المثال، إذا كنت تبيع مجموعة من الأجهزة لعميل ما، فسيطلب منك الحصول على الأجهزة التي يستخدمها هذا العميل.

يعرض هذا المثال طريقة واحدة لمعالجة مجموعة من الأجهزة التي تتضمن طلبات أجهزة من عدة شركات مصنّعة (Samsung وغيرها من أجهزة Android) من عدة عملاء.

الخطوة 1: تنظيم الأجهزة والعملاء

بالنظر إلى جدول يضمّ أرقام IMEI للأجهزة والشركات المصنّعة وأرقام تعريف العملاء الذين تم بيع الأجهزة لهم، تتمثّل إحدى طرق إدارة الطلبات في تنظيم هذه القوائم في قائمتَين: طلبات أجهزة Samsung وطلبات أجهزة أخرى (غير تابعة لشركة Samsung) تعمل بنظام التشغيل Android. وبعد ذلك، يمكنك تجميع الأجهزة بحسب العميل لكل قائمة. مثلاً:

أجهزة Samsung

اسم العميل الرقم التعريفي لعميل Samsung Knox الشركة المصنِّعة IMEI
شركة ABC 11 Samsung

1234567801

1234567802

الأجهزة الأخرى التي تعمل بنظام التشغيل Android

اسم العميل الرقم التعريفي للعميل الشركة المصنِّعة IMEI
شركة ABC 21 Google 1234567803
شركة XYZ 22 Sony

1234567804

1234567805

الخطوة 2: إنشاء كائن ClaimDevicesRequest

أجهزة Samsung

// Note: You can only claim devices for a single customer in each request.
ClaimDevicesRequest claimSamsungDevicesRequest = ClaimDevicesRequest.newBuilder()
   .addClaims(
       DeviceClaim.newBuilder()
           .setCustomer(
               CompanyReference.newBuilder()
                   .setVendor(Vendor.SAMSUNG)
                   .setCompanyId("11")
                   .build())
           .setDeviceIdentifier(
               DeviceIdentifier.newBuilder()
                   .setImei("1234567801")
                   .setManufacturer("Samsung")
                   .build())
       .build())
   .addClaims(
       DeviceClaim.newBuilder()
           .setCustomer(
               CompanyReference.newBuilder()
                   .setVendor(Vendor.SAMSUNG)
                   .setCompanyId("11")
                   .build())
           .setDeviceIdentifier(
               DeviceIdentifier.newBuilder()
                   .setImei("1234567802")
                   .setManufacturer("Samsung")
                   .build())
           .build())
   .build();

الأجهزة الأخرى التي تعمل بنظام التشغيل Android

ClaimDevicesRequest claimGoogleDevicesRequest = ClaimDevicesRequest.newBuilder()
    .addClaims(
        DeviceClaim.newBuilder()
            .setCustomer(
                CompanyReference.newBuilder()
                    .setVendor(Vendor.GOOGLE)
                    .setCompanyId("21")
                    .build())
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567803")
                    .setManufacturer("Google")
                    .build())
            .build())
    .addClaims(
        DeviceClaim.newBuilder()
            .setCustomer(
                CompanyReference.newBuilder()
                    .setVendor(Vendor.GOOGLE)
                    .setCompanyId("22")
                    .build())
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567804")
                    .setManufacturer("Sony")
                    .build())
            .build())
    .addClaims(
         DeviceClaim.newBuilder()
             .setCustomer(
                 CompanyReference.newBuilder()
                     .setVendor(Vendor.GOOGLE)
                     .setCompanyId("22")
                     .build())
             .setDeviceIdentifier(
                 DeviceIdentifier.newBuilder()
                     .setImei("1234567805")
                     .setManufacturer("Sony")
                     .build())
             .build())
    .build();

الخطوة 3: المطالبة بالأجهزة للعملاء

للمطالبة بأجهزة خاصة بالعملاء، يُرجى الاتصال بالرقم ClaimDevicesAsync. يتطلب هذا المثال طلبين منفصلين: أحدهما من كائن Samsung ResellerService وواحد من كائن Google ResellerService.

// Samsung devices
ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

// Other Android devices
ClaimDevicesResponse googleResponse = googleResellerService.claimDevicesAsync(claimGoogleDevicesRequest);

يعرض طلب ClaimDevicesAsync قائمة بـ Operation من العناصر التي تحتوي على حالة الطلب (قيد التقدم، أو اكتمال، أو مع وجود أخطاء، أو تعذّر تنفيذه). للتحقق من حالة العملية (على سبيل المثال، إذا عرضت الاستجابة IN_PROGRESS)، اتصل على getOperation.

// Samsung devices
GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

// Other Android devices
GetOperationRequest googleOperationRequest = GetOperationRequest.newBuilder().setOperationId(googleOperationId).build();
Operation googleOperation = googleResellerService.getOperation(googleOperationRequest);

إلغاء المطالبة بمجموعة من الأجهزة

تؤدي إزالة المطالبة بجهاز إلى إلغاء ربطه بأحد العملاء. قد تحتاج إلى إلغاء المطالبة بالجهاز في حال إلغاء طلب الجهاز أو تعذُّر اكتمال شحن الأجهزة. لإلغاء المطالبة بمجموعة من الأجهزة، اتبع الخطوات التالية:

الخطوة 1: إنشاء كائن UnclaimDevicesRequest

أجهزة Samsung

// Each request can only unclaim devices belonging to a single customer. The request must also
// include the customer's Samsung Knox customer ID.
UnclaimDevicesRequest unclaimSamsungDevicesRequest = UnclaimDevicesRequest.newBuilder()
    .putVendorParams("customerId", "11")
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567801")
                    .build())
        .build())
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567802")
                    .build())
            .build())
    .build();

الأجهزة الأخرى التي تعمل بنظام التشغيل Android

UnclaimDevicesRequest unclaimGoogleDevicesRequest = UnclaimDevicesRequest.newBuilder()
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567803")
                    .build())
            .build())
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567804")
                    .build())
            .build())
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567805")
                    .build())
            .build())
    .build();

الخطوة 2: إلغاء المطالبة بالأجهزة

لإلغاء المطالبة بأجهزة، اتصل برقم UnclaimDevicesAsync. يتطلب هذا المثال طلبين منفصلين: أحدهما من كائن Samsung ResellerService والآخر من كائن Google ResellerService.

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);
UnclaimDevicesResponse googleResponse = googleResellerService.unclaimDevicesAsync(unclaimGoogleDevicesRequest);

يعرض طلب UnclaimDevicesAsync قائمة بـ Operation من العناصر التي تحتوي على حالة الطلب (قيد التقدم، أو مكتملة، أو مع وجود أخطاء، أو أخفقت). للتحقق من حالة العملية (على سبيل المثال، إذا عرض الرد الاستجابة IN_PROGRESS)، فاتصل بـ getOperation.

أجهزة Samsung

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

الأجهزة الأخرى التي تعمل بنظام التشغيل Android

GetOperationRequest googleOperationRequest = GetOperationRequest.newBuilder().setOperationId(googleOperationId).build();
Operation googleOperation = googleResellerService.getOperation(googleOperationRequest);

استبدال جهاز Samsung

في حال كان هناك حاجة إلى استبدال الجهاز لأي سبب، يمكنك استبداله. يفترض هذا المثال أنك تستبدل جهاز Samsung بجهاز Samsung آخر.

الخطوة 1: إنشاء كائن UnclaimDeviceRequest

// Note: The request must include the customer's Samsung Knox customer ID.
UnclaimDevicesRequest unclaimSamsungDevicesRequest = UnclaimDevicesRequest.newBuilder()
    .putVendorParams("customerId", "11")
    .addUnclaims(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567801")
                    .build())
        .build())
    .build();

الخطوة 2: الاتصال بـ UnclaimDeviceAsync

UnclaimDevicesResponse samsungResponse = samsungResellerService.unclaimDevicesAsync(unclaimSamsungDevicesRequest);

يعرض الطلب UnclaimDevicesAsync قائمة تتضمّن Operation عناصر، والتي تتضمّن حالة الطلب (قيد التقدم، أو مكتملة، أو تتضمن أخطاء، أو تعذّر تنفيذها). للتحقق من حالة العملية (على سبيل المثال، إذا عرضت الاستجابة IN_PROGRESS)، اتصل بالرقم getOperation:

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

الخطوة 3: إنشاء كائن ClaimDeviceRequest

ClaimDevicesRequest claimSamsungDevicesRequest = ClaimDevicesRequest.newBuilder()
   .addClaims(
       DeviceClaim.newBuilder()
           .setCustomer(
               CompanyReference.newBuilder()
                   .setVendor(Vendor.SAMSUNG)
                   .setCompanyId("11")
                   .build())
           .setDeviceIdentifier(
               DeviceIdentifier.newBuilder()
                   .setImei("1234567806")
                   .setManufacturer("Samsung")
                   .build())
       .build())
   .build();

الخطوة 4: الاتصال بـ ClaimDeviceAsync

ClaimDevicesResponse samsungResponse = samsungResellerService.claimDevicesAsync(claimSamsungDevicesRequest);

يعرض الطلب ClaimDevicesAsync قائمة تتضمّن Operation عناصر، والتي تتضمّن حالة الطلب (قيد التقدم أو مكتملة أو تتضمّن أخطاء أو تعذّر تنفيذها). للتحقق من حالة العملية (على سبيل المثال، إذا عرضت الاستجابة IN_PROGRESS)، اتصل بالرقم getOperation:

GetOperationRequest samsungOperationRequest = GetOperationRequest.newBuilder().setOperationId(samsungOperationId).build();
Operation samsungOperation = samsungResellerService.getOperation(samsungOperationRequest);

استبدال جهاز Android (بخلاف Samsung)

في حال كان هناك حاجة إلى استبدال الجهاز لأي سبب، يمكنك استبداله. يفترض هذا المثال أنك تستبدل جهازًا يعمل بنظام التشغيل Android (بخلاف Samsung) بجهاز يعمل بنظام التشغيل Android (غير تابع لشركة Samsung).

الخطوة 1: إنشاء كائن UnclaimDeviceRequest

UnclaimDeviceRequest unclaimGoogleDeviceRequest = UnclaimDeviceRequest.newBuilder()
    .setUnclaim(
        DeviceUnclaim.newBuilder()
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567803")
                    .build())
            .build())
    .build();

الخطوة 2: الاتصال بـ UnclaimDevice

googleResponse = googleResellerService.unclaimDevice(unclaimGoogleDeviceRequest);

الخطوة 3: إنشاء كائن ClaimDeviceRequest

ClaimDeviceRequest claimGoogleDeviceRequest = ClaimDeviceRequest.newBuilder()
    .setClaim(
        DeviceClaim.newBuilder()
            .setCustomer(
                CompanyReference.newBuilder()
                    .setVendor(Vendor.GOOGLE)
                    .setCompanyId("21")
                    .build())
            .setDeviceIdentifier(
                DeviceIdentifier.newBuilder()
                    .setImei("1234567807")
                    .setManufacturer("Google")
                    .build())
            .build())
       .build();

الخطوة 4: الاتصال بـ ClaimDevice

ClaimDeviceResponse response = googleResellerService.claimDevice(claimGoogleDeviceRequest);

إذا نجحت العملية، سيتم عرض كائن ClaimDeviceResponse يحتوي على deviceId. وإلا، فإنها تعرض استثناءً شائعًا يحتوي على رمز خطأ.