פעולות נפוצות

בדף הזה מפורטות דוגמאות לפעולות נפוצות שאפשר לבצע באמצעות ספריית Android Reseller Library המשותפת, כולל:

יצירת אובייקטים מסוג ResellerService

משתמשים ב-classes המקוריות של 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

כדי לנהל מכשירי 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 corp 11 Samsung

1234567801

1234567802

מכשירי Android אחרים

שם הלקוח מספר לקוח היצרן IMEI
ABC corp 21 Google 1234567803
XYZ corp 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. אחרת, הוא יוצר חריג נפוץ שמכיל קוד שגיאה.