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

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

יצירת ResellerService אובייקטים

כדי ליצור ResellerService אובייקטים צריך להשתמש בכיתות המקוריות של Samsung ו-Google. בעזרת אובייקטים של 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. אפשר לאחזר את מספר הלקוח מהתשובה.

הצהרת בעלות על מספר מכשירים

תביעת בעלות על מכשיר יוצרת שיוך בין המכשיר ללקוח. לדוגמה, אם אתם מוכרים קבוצה של מכשירים ללקוח, תצטרכו לתבוע בעלות על המכשירים של הלקוח.

בדוגמה הזו מוצגת דרך אחת לעיבוד מספר רב של מכשירים, כולל הזמנות של מספר יצרנים (מכשירי Samsung ומכשירי Android נוספים) מלקוחות מרובים.

שלב 1: מארגנים את המכשירים והלקוחות

בטבלה של מספרי IMEI של המכשיר, היצרנים והמזהים של הלקוחות שנמכרו להם מכשירים, אחת הדרכים לנהל הזמנות היא לחלק אותן לשתי רשימות: הזמנות של מכשירי Samsung והזמנות אחרות של מכשירי Android (שאינם של Samsung). לאחר מכן, לכל רשימה, מקבצים מכשירים לפי לקוח. למשל:

מכשירי Samsung

שם לקוח מספר לקוח ב-Samsung Knox היצרן IMEI
אבג 11 Samsung

1234567801

1234567802

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

שם לקוח מספר לקוח היצרן IMEI
אבג 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. בדוגמה הזו נדרשות שתי בקשות נפרדות: אחת מהאובייקט Samsung ResellerService והשנייה מהאובייקט 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. אחרת הוא יוצר חריגה נפוצה שמכילה קוד שגיאה.