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

تقدّم هذه الصفحة أمثلة على بعض العمليات الشائعة التي يمكنك إجراؤها باستخدام مكتبة "مورّدي أجهزة Android العاديين"، بما في ذلك:

إنشاء ResellerService عنصر

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

أجهزة Samsung

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

لإجراء ذلك، عليك الانضمام إلى برنامج نشر Knox (KDP).

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

أجهزة Android الأخرى

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

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

إنشاء Customer عنصر

يحتاج العميل الذي يشتري أجهزة Samsung وغير 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. يمكنك retrieving the customer ID from the response.

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

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

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

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

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

أجهزة 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. تتطلّب هذه الأمثلة طلبَين منفصلَين: أحدهما من عنصر ResellerService في Samsung والآخر من عنصر ResellerService في Google.

// 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. يتطلّب هذا المثال طلبَين منفصلَين: أحدهما من كائن ResellerService Samsung والآخر عن كائن ResellerService Google.

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. وبخلاف ذلك، يتم طرح استثناء شائع يحتوي على رمز خطأ.