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

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

• إنشاء عناصر ResellerService
• إنشاء عناصر Customer
• المطالبة بمجموعة من الأجهزة
• إلغاء المطالبة بمجموعة من الأجهزة
• تبديل جهاز Samsung
• تبديل جهاز Android (غير تابع لهواتف Samsung)

---

إنشاء ResellerService عنصر

يمكنك استخدام فئات Samsung وGoogle Manufacturer Center لإنشاء عناصر "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

لإدارة أجهزة 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 وغيرها من طلبات أجهزة 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 وواحد من كائن 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. يتطلب هذا المثال اثنين طلبان منفصلان: واحد من كائن 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 وإلا، فإنها تعرض استثناءً شائعًا يحتوي على رمز خطأ.