裝置中繼資料

經銷商可以將電話號碼或採購單號碼等中繼資料與每部裝置建立關聯。您可以呼叫 API 建立中繼資料關聯，或在零接觸入口網站上傳 CSV 檔案。表 1 說明哪些使用者可以建立關聯及查看中繼資料：

表 1. 中繼資料權限

工作 經銷商 客戶
呼叫 API 關聯中繼資料
將 CSV 檔案上傳至 Zero-touch portal，即可建立中繼資料關聯
在 API 呼叫結果中查看裝置中繼資料
在零接觸入口網站中查看裝置中繼資料

指派中繼資料

如要將中繼資料與每個裝置建立關聯，請呼叫 partners.devices.metadata 方法。您可以使用下表 2 的按鍵，為 Android 裝置新增電話號碼和訂單號碼：

表格 2。Android 裝置的中繼資料鍵

資料 鍵 值類型 範例
電話號碼 phonenumber 字串 +1 (800) 555-0100
訂單號碼 ordernumber 字串 GOOG#123/ABC-123456

這兩個中繼資料值都是任意格式的字串，因此您可以採用適合貴機構的格式。

如果是 ChromeOS 裝置，可以使用下表 3 中的按鍵：

表 3. ChromeOS 裝置的中繼資料鍵

資料 鍵 值類型 範例
訂單號碼 ordernumber 字串 GOOG#123/ABC-123456
資產 ID annotatedassetid 字串 CORP-001234
位置 annotatedlocation 字串 紐約
已指派的使用者 annotateduser 字串 王志明

如要在建立裝置時指派中繼資料，請在呼叫 claimAsync 時加入中繼資料。以下範例說明如何為現有裝置 TARGET_DEVICE_ID 設定電話號碼和訂單編號：

Java

// Allowed metadata dictionary keys.
private static String METADATA_KEY_PHONE_NUMBER = "phonenumber";
private static String METADATA_KEY_ORDER_NUMBER = "ordernumber";

// ...
// Create the metadata record with the values.
DeviceMetadata metadata = new DeviceMetadata();
Map<String,String> entries = new HashMap<String, String>();
entries.put(METADATA_KEY_ORDER_NUMBER, "GOOG123/ABC-#123456");
entries.put(METADATA_KEY_PHONE_NUMBER, "+1 (800) 555-0100");
metadata.setEntries(entries);

// Set the metadata values on the target device.
UpdateDeviceMetadataRequest body = new UpdateDeviceMetadataRequest();
body.setDeviceMetadata(metadata);

DeviceMetadata response = service
        .partners()
        .devices()
        .metadata(PARTNER_ID, targetDeviceId, body)
        .execute();

.NET

// Allowed metadata dictionary keys.
private static string MetadataKeyPhoneNumber = "phonenumber";
private static string MetadataKeyOrderNumber = "ordernumber";

// ...
// Create the metadata record with the values.
DeviceMetadata metadata = new DeviceMetadata
{
    Entries = new Dictionary<string, string> {
        {MetadataKeyOrderNumber, "GOOG123/ABC-#123456"},
        {MetadataKeyPhoneNumber, "+1 (800) 555-0100"}
    }
};

// Set the metadata values on the target device.
UpdateDeviceMetadataRequest body = new UpdateDeviceMetadataRequest
{
    DeviceMetadata = metadata
};
var request = service.Partners.Devices.Metadata(body, PartnerId, targetDeviceId);
var results = request.Execute();

Python

# Allowed metadata dictionary keys.
METADATA_KEY_ENTRIES = "entries";
METADATA_KEY_PHONE_NUMBER = "phonenumber";
METADATA_KEY_ORDER_NUMBER = "ordernumber";

# ...
# Create the record with values.
new_metadata = {METADATA_KEY_ENTRIES:{ \
    METADATA_KEY_PHONE_NUMBER:'+1 (800) 555-0100', \
    METADATA_KEY_ORDER_NUMBER:'GOOG123/ABC-#123456'}}

# Set the metadata values on the target device.
response = service.partners().devices().metadata(
    metadataOwnerId=PARTNER_ID,
    deviceId=target_device_id,
    body={'deviceMetadata':new_metadata}).execute()

中繼資料引數會取代相同鍵的現有中繼資料值。

刪除中繼資料

你可以從裝置刪除中繼資料。針對要刪除的中繼資料值傳遞空字串。以下範例說明如何刪除電話號碼：

Java

// Create the metadata record with the values.
DeviceMetadata metadata = new DeviceMetadata();
Map<String,String> entries = new HashMap<String, String>();
entries.put(METADATA_KEY_PHONE_NUMBER, "");
metadata.setEntries(entries);

// Call partners().devices().metadata() to remove the phone metadata from the device...

.NET

// Create the metadata record with empty values.
DeviceMetadata metadata = new DeviceMetadata
{
    Entries = new Dictionary<string, string> {
        {MetadataKeyPhoneNumber, ""}
    }
};

// Call Partners.Devices.Metadata to remove the phone metadata from the device...

Python

# Create the metadata record with empty values.
metadata_to_remove = {METADATA_KEY_ENTRIES: {METADATA_KEY_PHONE_NUMBER:''}}

# Call partners().devices().metadata() to remove the phone number
# metadata from the device...