EdgeHub GraphQL API example

1. GraphQL Tools

1.1 GraphQL Playground

URL Information

Please use the built-in GraphQL Playground tool on the EdgeHub site for API testing.
The location is
https:///graphql
For example, on the EdgeHub master site, the GraphQL Playground is located at
https://pivot-api-hub-master-ensaas.edge365.advantech.com/graphql
Cookie Settings

EdgeHub GraphQL API utilizes cookies to record relevant login information. To ensure the proper functioning of the playground, settings must be configured on the interface.
- Click on the settings icon in the top left corner of the screen.
- In the popped-up dialog box, change the Include cookies setting to ON, then click Save to save the configuration.
After configuration, you can enter GraphQL commands in the center of the screen according to the instructions in this document, click Run, and finally, obtain the API return results on the right side of the screen.

2. Pre-Request: Requests that must be performed before all other requests

Introduction Log in with valid account credentials. Upon successful login, you can obtain information about the tenant with user permissions and Token information.

Request

mutation{
  signIn(input:{
    username:sa.jing@advantech.com.cn
    password:123qwerty
  }){

    user{
      username
      tenants{
        id name
      }
    }
    ifpToken
  }
} 

Response

{
data: {
  signIn: {
    user: {
      username: sa.jing@advantech.com.cn,
      tenants: [
        {
          id: VGVuYW50.Y1-NK3QAXhVOdBTZ,
          name: Root Tenant
        },
        {
          id: VGVuYW50.ZDet-2iqhavNUEAg,
          name: satest
        },
        {
          id: VGVuYW50.ZEDrEXytTpwoOFpi,
          name: devPlayground
        }
      ]
    },
    "ifpToken": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJjb3VudHJ5IjoiVFciLCJjcmVhdGlvblRpbWUiOjE2NjczNjY3NDIsImV4cCI6MTY4ODQ1OTk1NCwiZmlyc3ROYW1lIjoiU2EiLCJpYXQiOjE2ODg0NTYzNTQsImlkIjoiY2I5MmU2M2YtNWE2ZS0xMWVkLTgyNzYtMGE1ODBhZGY0MGNkIiwiaXNzIjoid2lzZS1wYWFzIiwibGFzdE1vZGlmaWVkVGltZSI6MTY2NzM2ODAxOSwibGFzdE5hbWUiOiJKaW5nIiwicmVmcmVzaFRva2VuIjoiZGZiMmU2YzctMWEzZC0xMWVlLTg4YmQtMGE1ODBhZGY0MGRiIiwic3RhdHVzIjoiQWN0aXZlIiwidXNlcm5hbWUiOiJzYS5qaW5nQGFkdmFudGVjaC5jb20uY24ifQ.EHHy72agREj2GpNJ0Za-CzCxNyA8Xc3Zw2BGSzFemAqS06D_3MUCxndIqln8XkRtOBjVpzUFvSFkJqckF-obRw"
  }
}
}

Note If you are integrating with EdgeHub's GraphQL API in the backend development, you must manually include the following information in the API cookie to use it.

The content of the cookie is as follows:
- IFPToken: Carry the content of ifpToken from the signIn request response body, for example: IFPToken=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJjb3VudHJ5IjoiVFciLCJjcmVhdGlvblRpbWUiOjE2NjczNjY3NDIsImV4cCI6MTY4ODQ1OTk1NCwiZmlyc3ROYW1lIjoiU2EiLCJpYXQiOjE2ODg0NTYzNTQsImlkIjoiY2I5MmU2M2YtNWE2ZS0xMWVkLTgyNzYtMGE1ODBhZGY0MGNkIiwiaXNzIjoid2lzZS1wYWFzIiwibGFzdE1vZGlmaWVkVGltZSI6MTY2NzM2ODAxOSwibGFzdE5hbWUiOiJKaW5nIiwicmVmcmVzaFRva2VuIjoiZGZiMmU2YzctMWEzZC0xMWVlLTg4YmQtMGE1ODBhZGY0MGRiIiwic3RhdHVzIjoiQWN0aXZlIiwidXNlcm5hbWUiOiJzYS5qaW5nQGFkdmFudGVjaC5jb20uY24ifQ.EHHy72agREj2GpNJ0Za-CzCxNyA8Xc3Zw2BGSzFemAqS06D_3MUCxndIqln8XkRtOBjVpzUFvSFkJqckF-obRw
- EIToken: Carry the content of ifpToken from the signIn request response body, for example: EIToken=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJjb3VudHJ5IjoiVFciLCJjcmVhdGlvblRpbWUiOjE2NjczNjY3NDIsImV4cCI6MTY4ODQ1OTk1NCwiZmlyc3ROYW1lIjoiU2EiLCJpYXQiOjE2ODg0NTYzNTQsImlkIjoiY2I5MmU2M2YtNWE2ZS0xMWVkLTgyNzYtMGE1ODBhZGY0MGNkIiwiaXNzIjoid2lzZS1wYWFzIiwibGFzdE1vZGlmaWVkVGltZSI6MTY2NzM2ODAxOSwibGFzdE5hbWUiOiJKaW5nIiwicmVmcmVzaFRva2VuIjoiZGZiMmU2YzctMWEzZC0xMWVlLTg4YmQtMGE1ODBhZGY0MGRiIiwic3RhdHVzIjoiQWN0aXZlIiwidXNlcm5hbWUiOiJzYS5qaW5nQGFkdmFudGVjaC5jb20uY24ifQ.EHHy72agREj2GpNJ0Za-CzCxNyA8Xc3Zw2BGSzFemAqS06D_3MUCxndIqln8XkRtOBjVpzUFvSFkJqckF-obRw
- IFPTenant：Carry the tenant ID from the signIn request response body, for example:
  IFPTenant=VGVuYW50.ZDet-2iqhavNUEAg
- Header example

2.2 setMyTenant

Introduction Set the current tenant for the logged-in user. Subsequent API calls require information about which tenant's data is to be retrieved.

Request

mutation{
  setMyTenant(input:{
    tenantId:VGVuYW50.Y1ipFJlXsFyvoFGT
  }){tenant{
    id name
      }}
}

Response

{
  data: {
    setMyTenant: {
      tenant: {
        id: VGVuYW50.Y1ipFJlXsFyvoFGT,
        name: sa
      }
    }
  }
}

Note If you are developing the backend integration with EdgeHub's GraphQL API, this step may not be necessary. Simply ensure that the correct tenant ID (IFPTenant) is included in the subsequent API cookies.

3. Common API Examples

3.1 groups

3.1.1 All groups

Introduction Retrieve information about all groups under this tenant.

Request

{
  groups{
    id 
    name
    description
    depth
  }
} 

Response

{
  data: {
    groups: [
      {
        id: R3JvdXA.NQ,
        name: L2-1,
        description: ,
        depth: 2
      },
      {
        id: R3JvdXA.Ng,
        name: L3-1,
        description: ,
        depth: 3
      },
      {
        id: R3JvdXA.Nw,
        name: L2-2,
        description: L2-2,
        depth: 2
      },
      {
        id: R3JvdXA.NA,
        name: Edge365-test1025,
        description: ,
        depth: 1
      }
    ]
  }
}

3.1.2 Only root group

Introduction GET the root group (depth=1) only under the current tenant.

Request

{
  groups(rootGroupsOnly:true){
    id name depth
  }
} 

{  
  groups(level:1){
    id name depth
  }
}

Response

{
  data: {
    groups: [
      {
        id: R3JvdXA.NA,
        name: Edge365-test1025,
        depth: 1
      }
    ]
  }
}

3.2 machines (objects)

3.2.1 All machines (objects)

Introduction Get all machines (objects) under a specific group.

Request

{
  group(id:R3JvdXA.Mjc){
    id name depth
    machines{
      id name isGroupObject machineType{
        parentKey key
      }
    }
  }
}

Response

{
  data: {
    group: {
      id: R3JvdXA.Mjc,
      name: Advantech-PAE,
      depth: 1,
      machines: [
        {
          id: TWFjaGluZQ.NzE,
          name: Advantech-PAE,
          isGroupObject: true,
          machineType: {
            parentKey: default,
            key: GroupObject
          }
        },
        {
          id: TWFjaGluZQ.ODky,
          name: WISE4051_Jim,
          isGroupObject: false,
          machineType: {
            parentKey: default,
            key: DefaultEquipType
          }
        }
      ]
    }
  }
}

3.2.2 All machines (objects) except “GroupObject”

Introduction Get all machines (objects) under a specific group, excluding the GroupObject (automatically generated and named the same as the current group).

Request

{
  group(id:R3JvdXA.Mjc){
    id name depth
    machines(showGroupObject:false){
      id name isGroupObject machineType{
        parentKey key
      }
    }
  }
}

Response

{
  data: {
    group: {
      id: R3JvdXA.Mjc,
      name: Advantech-PAE,
      depth: 1,
      machines: [
        {
          id: TWFjaGluZQ.ODky,
          name: WISE4051_Jim,
          isGroupObject: false,
          machineType: {
            parentKey: default,
            key: DefaultEquipType
          }
        }
      ]
    }
  }
}

3.3 parameters

3.3.1 parameters

Introduction Get all parameters under a specific machine (object).

Request

{
  machine(id:TWFjaGluZQ.ODky){
    parameters{
        nodes{
          id 
          name
          scadaId
          tagId
          valueType
          kind
          spanHi
          spanLo
          unit
          recordingType
          recordingRate
        }
      }
  }
} 

Response

{
  data: {
    machine: {
      parameters: {
        nodes: [
          {
            id: UGFyYW1ldGVy.ODkyJkRJXzA,
            name: DI_0,
            scadaId: 00D0C9E3696F,
            tagId: di0,
            valueType: Number,
            kind: null,
            spanHi: 1,
            spanLo: 0,
            unit: ,
            recordingType: Current,
            recordingRate: 300
          },
          {
            id: UGFyYW1ldGVy.ODkyJkRJXzE,
            name: DI_1,
            scadaId: 00D0C9E3696F,
            tagId: di1,
            valueType: Discrete,
            kind: null,
            spanHi: 1,
            spanLo: 0,
            unit: ,
            recordingType: Current,
            recordingRate: 300
          },
          {
            id: UGFyYW1ldGVy.ODkyJmNvbTFjb2lsMDAx,
            name: com1coil001,
            scadaId: 00D0C9E3696F,
            tagId: com1coil002,
            valueType: Discrete,
            kind: null,
            spanHi: 1,
            spanLo: 0,
            unit: ,
            recordingType: Current,
            recordingRate: 300
          }
        ]
      }
    }
  }
}

3.3.2 parameter value

Introduction Query the value of a specific parameter. In the returned data, if it is a numerical type, it can be obtained in the num field; if it is a text type, it can be obtained in the str field.

Request

{
  parameter(id:UGFyYW1ldGVy.ODkyJjk2UEQtVEhTMTZCX1JI){
    dcLastValue{
      num
      str
      time
    }
  }
}

Response

{
  data: {
    parameter: {
      dcLastValue: {
        num: 0,
        str: null,
        time: 1690806255000
      }
    }
  }
}

3.4 gateways (devices)

3.4.1 gateways (devices) information without tags

Introduction Retrieve information about all gateways (devices) under a specific tenant. It is recommended not to simultaneously retrieve tag information when obtaining gateways to avoid impacting efficiency due to a large amount of returned data.

Request

{
  dcGateways {
    id
    name
    scadaId
    credentialKey
    currentStatus {
      status
    }
    kind
    tagCount
  }
}

Response

{
  data: {
    dcGateways: [
      {
        id: R2F0ZXdheQ.NDEy,
        name: aaaaaaaaaaaaaaaaa,
        scadaId: aaaaddc0-65f3-11wd-87e2-87b77e93fff3,
        credentialKey: SharedAccessSignature sr=edg-iothub.azure-devices.net%2Fdevices%2Faaaaddc0-65f3-11wd-87e2-87b77e93fff3&amp;sig=WYzkH1T05PO5SRwefwefwevBu3bga3adfsdfsdfdsZcV4fdRA%3D&amp;se=4823334283&amp;skn=device,
        currentStatus: {
          status: false
        },
        "kind": "DcSCADA",
        "tagCount": 1
      },
      {
        id: R2F0ZXdheQ.Mjc5MTI,
        name: ADAM-6060-AutoTest,
        scadaId: 00D0C9999999,
        credentialKey: HostName=edge365-iothub.azure-devices.net;DeviceId=00D0C9999999;SharedAccessKey=e+3SMg6jrC/Ys4FJJeYNwfwefwefwefrfwfwe8AIoTFNbnFA=,
        currentStatus: {
          status: true
        },
        "kind": "DcADAM",
        "tagCount": 17
      }
    ]
  }
}

3.4.2 Get gateway (device) by SCADA Id

Introduction Using the method introduced in section 3.4.1 to obtain the ScadaId of a specific device. Then utilize this API to retrieve the tag information for that individual device.

Request

{
  dcGatewayByScadaId(scadaId: 00D0C9999999) {
    id
    name
    tagCount  
    dcTags {
      nodes {
        tagId
        dcIsNum
        dcDataValue
        dcDataTime
        dcQuality
      }
    }
  }
}

Response

{
data: {
  dcGatewayByScadaId: {
    id: R2F0ZXdheQ.Mjc5MTI,
    name: ADAM-6060-AutoTest,
    tagCount: 4,
    dcTags: {
      nodes: [
        {
          tagId: #MSYS_EdgeStatus,
          dcIsNum: true,
          dcDataValue: 1,
          dcDataTime: 1699933491379,
          dcQuality: 0
        },
        {
          tagId: di0,
          dcIsNum: true,
          dcDataValue: 0,
          dcDataTime: 1700045509058,
          dcQuality: 0
        },
        {
          tagId: do0,
          dcIsNum: true,
          dcDataValue: 1,
          dcDataTime: 1700045509058,
          dcQuality: 0
        },
        {
          tagId: ipaddr,
          dcIsNum: false,
          dcDataValue: 172.16.12.172,
          dcDataTime: 1699933491380,
          dcQuality: 0
        }
      ]
    }
  }
}
}

3.5 Users

3.5.1 Add new user to current tenant

Introduction Add a completely new user to the current tenant. In this context, a "completely new user" refers to a user for whom a query of publicUser returns null. In such a scenario, the addUser API should be used to add the user.

Request (query public user)

{
  publicUser(username: b.c@gmail.com) {
    username
  }
}

Response (query public user)
```
{
  data: {
    publicUser: null
  }
}
```

Request (addUser)

mutation($input: AddUserInput!){
  addUser(input: $input) {
    user {
      id
      username
    }
  }
}

Variables:
{
  input: {
    username: b.c@gmail.com,
    name: b.c,
    firstName:b,
    lastName:c,
    roles:[Admin]
  }
}

Response (addUser)

{
  data: {
    addUser: {
      user: {
        id: VXNlcg.MTQ2,
        username: b.c@gmail.com
      }
    }
  }
}

3.5.2 Add exist user to specified tenant

Introduction Add an existing user to the current tenant. In this context, an "existing user" refers to a user for whom a query of publicUser returns accurate user information. In such a scenario, the setTenantUser API should be used to add the user.

Request (query public user)

{
  publicUser(username: b.c@gmail.com) {
    userId
    username
  }
}

Response (query public user) - 可以取得正確的userId與username

{
  data: {
    publicUser: {
      userId: VXNlcg.Mg,
      username: b.c@gmail.com
    }
  }
}

Request (setTenantUser) - 需攜帶public user取得的userId

mutation($input: SetTenantUserInput!){
  setTenantUser(input: $input) {
    tenantUser {
      userId
      tenantId
    }
  }
}

Variables:
{
  input: {
    userId: VXNlcg.Mg,
    tenantId: VGVuYW50.ZFi5Je28lVQe3g8s,
    roles:[Admin],
    active: true
  }
}

Response (setTenantUser)

{
  data: {
    setTenantUser: {
      tenantUser: {
        userId: VXNlcg.Mg,
        tenantId: VGVuYW50.ZFi5Je28lVQe3g8s
      }
    }
  }
}

3.5.3 Tenant user's roles & scopes

Introduction
- Utilize the user information of EIToken and tenant ID within the Cookie to query the roles and scopes of that user in the specified tenant.
- In this API request, the roleDetails field allows you to inquire about various types of permissions, including (orgAcls / dhAcls / reAcls / biAcls). For the mapping between each type of scope and the names on the EdgeHub portal - role page, please refer to Chapter 4. Choose the desired type and fill in this field.

Request

{
  me {
    tenant {      
      myTenantUser {
        roles
        roleDetails {
          orgAcls {
            mode
            scope
          }
          dhAcls {
            mode
            scope
          }
        }
      }
    }
  }
}

Response

{
  data: {
    me: {
      tenant: {
        myTenantUser: {
          roles: [
            Admin
          ],
          roleDetails: [
            {
              orgAcls: [
                {
                  mode: Manage,
                  scope: User
                },
                {
                  mode: Manage,
                  scope: GMP
                },
                ...
                ...
                ...
                {
                  mode: Manage,
                  scope: Others
                }
              ],
              "dhAcls": [
                {
                  mode: Manage,
                  scope: InOutbound
                },
                {
                  mode: Manage,
                  scope: Others
                }
              ]
            }
          ]
        }
      }
    }
  }
}

3.5.4 Group user's roles & scopes

Introduction
- Utilize the user information of EIToken and tenant ID within the Cookie to query the roles and scopes of that user in a specific group under the given tenant.
- In this API request, the myGroupUser field allows you to inquire about various types of permissions, including (orgAcls / dhAcls / reAcls / biAcls). For the mapping between each type of scope and the names on the EdgeHub portal - role page, please refer to Chapter 4. Choose the desired type and fill in this field.

Request

{
  group(id: R3JvdXA.NTE) {
    myGroupUser {
      roles
      dhAcls{
        mode
        scope
      }
    }
  }
}

Response

{
  data: {
    group: {
      myGroupUser: {
        roles: [
          Admin
        ],
        dhAcls: [
          {
            mode: Manage,
            scope: InOutbound
          },
          {
            mode: Manage,
            scope: Others
          }
        ]
      }
    }
  }
}

3.6 signOut

Introduction Log out of this account. After logging out, you won't be able to call the above APIs unless you log in again.
Request
```
mutation{
  signOut
}  
```
Response
```
{
  data: {
    signOut: null
  }
}
```

4. The mapping table for Scope / ACLs

Object Management

Display Name	ACL	scope
Group, Object, and Parameter	orgAcls	GMP
Alarm and Event	reAcls	HighLowEvent
Profile Management	orgAcls	Profile
Machine Status	orgAcls	MachineStatus
Rule Management	orgAcls	MappingRule
In-Outbound Settings	dhAcls	InOutbound
Others (Organizer)	orgAcls	Others
Others (Data Hub)	dhAcls	Others
Others (Rule Engine)	reAcls	Others

User Management

Display Name	ACL	scope
User List	orgAcls	User
Client List	orgAcls	Client
Role List	orgAcls	Role

Command Center

Display Name	ACL	scope
Command Center Settings	orgAcls	Cmdc
Dashboard & Menu List	biAcls	Dashboard

System Setting

Display Name	ACL	scope
License	orgAcls	License
Authority Management	orgAcls	Permission

WISE-PaaS Dashboard

Display Name	ACL	scope
Value and Alarm	biAcls	Alarm
Operation Log	biAcls	Log

1. GraphQL Tools​

1.1 GraphQL Playground​

2. Pre-Request: Requests that must be performed before all other requests​

2.1 signIn​

2.2 setMyTenant​

3. Common API Examples​

3.1 groups​

3.1.1 All groups​

3.1.2 Only root group​

3.2 machines (objects)​

3.2.1 All machines (objects)​

3.2.2 All machines (objects) except “GroupObject”​

3.3 parameters​

3.3.1 parameters​

3.3.2 parameter value​

3.4 gateways (devices)​

3.4.1 gateways (devices) information without tags​

3.4.2 Get gateway (device) by SCADA Id​

3.5 Users​

3.5.1 Add new user to current tenant​

3.5.2 Add exist user to specified tenant​

3.5.3 Tenant user's roles & scopes​

3.5.4 Group user's roles & scopes​

3.6 signOut​

4. The mapping table for Scope / ACLs​

Object Management​

User Management​

Command Center​

System Setting​

WISE-PaaS Dashboard​

Is this helpful?

1. GraphQL Tools

1.1 GraphQL Playground

2. Pre-Request: Requests that must be performed before all other requests

2.1 signIn

2.2 setMyTenant

3. Common API Examples

3.1 groups

3.1.1 All groups

3.1.2 Only root group

3.2 machines (objects)

3.2.1 All machines (objects)

3.2.2 All machines (objects) except “GroupObject”

3.3 parameters

3.3.1 parameters

3.3.2 parameter value

3.4 gateways (devices)

3.4.1 gateways (devices) information without tags

3.4.2 Get gateway (device) by SCADA Id

3.5 Users

3.5.1 Add new user to current tenant

3.5.2 Add exist user to specified tenant

3.5.3 Tenant user's roles & scopes

3.5.4 Group user's roles & scopes

3.6 signOut

4. The mapping table for Scope / ACLs

Object Management

User Management

Command Center

System Setting

WISE-PaaS Dashboard