Device Reference Helper¶
Overview¶
Many BIG-IQ API requests refer to a particular BIG-IP using the deviceReference parameter. The value of deviceReference is a link object for the BIG-IP being targeted by the request. You should first call the Device Reference Helper API to get the correct value of deviceReference before trying to use it in another BIG-IQ API. The value of these links is expected to change from release to release. The helper API can query for the correct value of deviceReference if you specify either the hostname, address, or machineId of the target BIG-IP as well as specify the module associated with your request. By using the helper API, you will isolate clients from future version-specific changes to these links.
The MachineId Resolver API can retrieve a device object, with some informational properties, for all of the currently trusted BIG-IPs on the system.
Requests¶
Examples¶
POST to retrieve deviceReference for PUT¶
In the following example, the BIG-IQ API is going to use the deviceReference parameter to target a particular BIG-IP for a PUT request. First, call the Device Reference Helper to get the correct value of deviceReference as follows.
POST https://<BIG-IQ>/mgmt/cm/shared/device-reference-query
The JSON in the body of the POST can look similar to the following.
{
"address": "192.0.0.106",
"module": "access"
}
On success, the body of the response contains the link object which is the value of deviceReference.
{
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-access-allBigIpDevices/devices/2913a9ff-6fea-42a1-bd82-73d6dd5c9849"
}
You can then use this value in the PUT request as the follows.
PUT https://<BIG-IQ>/mgmt/cm/access/working-config/ltm/virtual/<id>
The JSON in the body of the PUT can look similar to the following.
{
"name": "vip-02",
"deviceReference": {
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-access-allBigIpDevices/devices/2913a9ff-6fea-42a1-bd82-73d6dd5c9849"
}
}
POST to get deviceReference using machineId¶
The following example uses the BIG-IP’s machineId to retrieve the value of deviceReference for all device groups of the BIG-IP.
POST https://<BIG-IQ>/mgmt/cm/shared/device-reference-query
The JSON in the body of the POST request can look similar to the following. If module is null or empty, BIG-IQ uses a default value of “global”.
{
"machineId": "20d984d2-9da5-4b59-b78b-54d7bd6d11f2"
}
The JSON in the body of the response can look similar to the following.
{
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/7703cfab-ead2-4abd-984d-b61f259f705d"
}
You can then send a GET request to this link to retrieve the device object for the BIG-IP.
GET https://<BIG-IQ>/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/7703cfab-ead2-4abd-984d-b61f259f705d
The JSON in the body of the response can look similar to the following.
{
"kind": "shared:resolver:device-groups:restdeviceresolverdevicestate",
"uuid": "7703cfab-ead2-4abd-984d-b61f259f705d",
"build": "0.0.6",
"slots": [{
"build": "0.0.6",
"volume": "HD1.1",
"product": "BIG-IP",
"version": "13.1.3",
"isActive": true
}],
"state": "ACTIVE",
"address": "10.144.75.194",
"edition": "Final",
"product": "BIG-IP",
"version": "13.1.3",
"hostname": "joey.bipip13One3.com",
"selfLink": "https://localhost/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/7703cfab-ead2-4abd-984d-b61f259f705d",
"deviceUri": "https://10.144.75.194:443",
"groupName": "cm-bigip-allBigIpDevices",
"httpsPort": 443,
"isVirtual": true,
"machineId": "7703cfab-ead2-4abd-984d-b61f259f705d",
"generation": 4,
"properties": {
"shared:resolver:device-groups:discoverer": "20d984d2-9da5-4b59-b78b-54d7bd6d11f2"
},
"isClustered": false,
"mcpDeviceName": "/Common/joey.bipip13One3.com",
"trustDomainGuid": "8071dd39-c223-4b3c-bc63fa163e83a778",
"isLicenseExpired": false,
"lastUpdateMicros": 1575324951435097,
"managementAddress": "10.144.75.194",
"restFrameworkVersion": "13.1.3-0.0.6"
}
POST to get deviceReference using machineId¶
The following example uses the BIG-IP’s machineId to retrieve the value of deviceReference and specifies the device group associated with cm-adccore-allbigipDevices.
POST https://<BIG-IQ>/mgmt/cm/shared/device-reference-query
The JSON in the body of the POST request can look similar to the following.
{
"machineId": "20d984d2-9da5-4b59-b78b-54d7bd6d11f2",
"module": "adc-core"
}
The JSON in the body of the response can look similar to the following.
{
"link": "https://localhost/mgmt/shared/resolver/device-groups/cm-adccore-allbigipDevices/devices/7703cfab-ead2-4abd-984d-b61f259f705d"
}