python-glpi-api

Module for interacting with GLPI using the REST API. It just wraps endpoints provided by the API and manage HTTP return codes.

Helpers

glpi_api.connect(url, apptoken, auth, verify_certs=True, use_headers=True)

Context manager that authenticate to GLPI when enter and kill application session in GLPI when leaving:

>>> import glpi_api
>>>
>>> URL = 'https://glpi.exemple.com/apirest.php'
>>> APPTOKEN = 'YOURAPPTOKEN'
>>> USERTOKEN = 'YOURUSERTOKEN'
>>>
>>> try:
>>>     with glpi_api.connect(URL, APPTOKEN, USERTOKEN) as glpi:
>>>         print(glpi.get_config())
>>> except glpi_api.GLPIError as err:
>>>     print(str(err))

You can set verify_certs to False to ignore invalid SSL certificates.

use_headers indicates whether authentication parameters are sent through HTTP headers or as GET parameters (in the URL). The default is to use headers but some environments (cf this GLPI issue and the following Stack Overflow post) may require to use GET parameters.

API

class glpi_api.GLPI(url, apptoken, auth, verify_certs=True, use_headers=True)

Class for interacting with GLPI using the REST API.

The constructor authenticate to the GLPI platform at url using an application token apptoken (see API clients configuration) and either a string containing the user token or a couple of username/password as auth parameter:

# Authentication using user API token.
glpi = GLPI(url='https://glpi.exemple.com/apirest.php',
            apptoken='YOURAPPTOKEN',
            auth='YOURUSERTOKEN')
# Authentication using username/password.
glpi = GLPI(url='https://glpi.exemple.com/apirest.php',
            apptoken='YOURAPPTOKEN',
            auth=('USERNAME', 'PASSWORD'))

verify_certs and use_headers can be unset to respectively not checking SSL certificates and passing authentication parameters as GET parameters (instead of headers).

kill_session()

API documentation

Destroy a session identified by a session token. Note that this method is automatically called by the context manager connect.

>>> glpi.kill_session()
# Doing another actions will raise this error.
>>> glpi.list_search_options('Computer')
...
GLPIError: (ERROR_SESSION_TOKEN_INVALID) session_token semble incorrect

get_my_profiles()

API documentation

Return all the profiles associated to logged user.

>>> glpi.get_my_profiles()
[{'id': 2,
  'name': 'Observer',
  'entities': [{'id': 0, 'name': 'Root entity', 'is_recursive': 1}]},
 {'id': 8,
  'name': 'Read-Only',
  'entities': [{'id': 0, 'name': 'Root entity', 'is_recursive': 1}]}]

get_active_profile()

API documentation

Return the current active profile.

>>> glpi.get_active_profile()
{'id': 2,
 'name': 'Observer',
 'interface': 'central',
 'is_default': 0,
 ...

set_active_profile(profile_id)

API documentation

Change active profile to the profile_id one.

>>> glpi.get_active_profile()['name']
'Observer'
>>> glpi.set_active_profile(8)
>>> glpi.get_active_profile()['name']
'Read-Only'
>>> glpi.set_active_profile(4) # Invalid profile for user
GLPIError: (ERROR_ITEM_NOT_FOUND) Élément introuvable

get_my_entities()

API documentation

Return all the possible entities of the current logged user (and for current active profile).

>>> glpi.get_my_entities()
[{'id': 0, 'name': 'Root entity'}]

get_full_session()

API documentation

Return the current php $_SESSION.

>>> glpi.get_full_session()
{'glpi_plugins': {'1': 'fusioninventory', '2': 'racks', '3': 'fields'},
 'valid_id': '1ak1oms81ie61vhndhgp20b12a',
 'glpi_currenttime': '2018-09-06 14:52:31',
 ...

get_config()

API documentation

Return the current $CFG_GLPI.

>>> glpi.get_config()
{'cfg_glpi': {'languages': {'ar_SA': ['العَرَبِيَّةُ',
    'ar_SA.mo',
    'ar',
...

get_item(itemtype, item_id, **kwargs)

API documentation

Return the instance fields of itemtype identified by item_id. kwargs contains additional parameters allowed by the API.

>>> glpi.get_item('Computer', 1)
{'id': 1,
 'entities_id': 0,
 'name': 'test',
 ...
# Using with_logs extra request parameters.
>>> glpi.get_item('Computer', 1, with_logs=True)
{'id': 1,
 'entities_id': 0,
 'name': 'test',
 ...,
 '_logs': {
   '261': {
     'id': 261,
      'itemtype': 'Computer',
      'items_id': 1,
      ...

get_all_items(itemtype, **kwargs)

API documentation

Return a collection of rows of the itemtype. kwargs contains additional parameters allowed by the API.

# Retrieve (non deleted) computers.
>>> glpi.get_all_items('Computer')
[{'id': 1,
 'entities_id': 0,
 'name': 'test',
...
# Retrieve deleted computers.
>>> glpi.get_all_items('Computer', is_deleted=True)
[]
# Using searchText.
>>> glpi.get_all_items('Computer', searchText={'name':'server'})
[]

get_sub_items(itemtype, item_id, sub_itemtype, **kwargs)

API documentation

Return a collection of rows of the sub_itemtype for the identified item of type itemtype and id item_id. kwargs contains additional parameters allowed by the API.

# Retrieve logs of a computer.
>>> In [241]: glpi.get_sub_items('Computer', 1, 'Log')
[{'id': 261,
  'itemtype': 'Computer',
  'items_id': 1,
...

get_multiple_items(*items)

API documentation

Virtually call Get an item for each line in input. So, you can have a ticket, a user in the same query.

>>> glpi.get_multiple_items({'itemtype': 'User', 'items_id': 2},
                            {'itemtype': 'Computer', 'items_id': 1})
[{'id': 2,
  'name': 'glpi',
  ...},
 {'id': 1,
  'entities_id': 0,
  'name': 'test',
   ...}]

list_search_options(itemtype, raw=False)

API documentation

List the searchoptions of provided itemtype. raw return searchoption uncleaned (as provided by core).

>>> glpi.list_search_options('Computer')
{'common': {'name': 'Caractéristiques'},
 '1': {
  'name': 'Nom',
  'table': 'glpi_computers',
  'field': 'name',
  'datatype': 'itemlink',
  ...

field_id(itemtype, field_uid, refresh=False)

Return itemtype field id from field_uid. Each itemtype are “cached” (in _fields attribute) and will be retrieve once except if refresh is set.

>>> glpi.field_id('Computer', 'Entity.completename')
80

field_uid(itemtype, field_id, refresh=False)

Return itemtype field uid from field_id. Each itemtype are “cached” (in _fields attribute) and will be retrieve once except if refresh is set.

>>> glpi.field_id('Computer', 80)
'Entity.completename'

search(itemtype, **kwargs)

API documentation

Expose the GLPI searchEngine and combine criteria to retrieve a list of elements of specified itemtype.

# Retrieve
>>> criteria = [{'field': 45, 'searchtype': 'contains', 'value': '^Ubuntu$'}]
>>> forcedisplay = [1, 80, 45, 46] # name, entity, os name, os version
>>> glpi.search('Computer', criteria=criteria, forcedisplay=forcedisplay)
[{'1': 'test', '80': 'Root entity', '45': 'Ubuntu', '46': 16.04}]

# You can use fields uid instead of fields id.
>>> criteria = [{'field': 'Item_OperatingSystem.OperatingSystem.name',
                 'searchtype': 'contains',
                 'value': '^Ubuntu$'}]
>>> forcedisplay = [
        'name',
        'Entity.completename',
        'Item_OperatingSystem.OperatingSystem.name',
        'Item_OperatingSystem.OperatingSystemVersion.name']
>>> glpi.search('Computer', criteria=criteria, forcedisplay=forcedisplay)
[{'1': 'test', '80': 'Root entity', '45': 'Ubuntu', '46': 16.04}]

add(itemtype, *items)

API documentation

Add an object (or multiple objects) of type itemtype into GLPI.

>>> glpi.add('Computer',
             {'name': 'computer1', 'serial': '123456', 'entities_id': 0},
             {'name': 'computer2', 'serial': '234567', 'entities_id': 1})
[{'id': 5, 'message': ''}, {'id': 6, 'message': ''}]

update(itemtype, *items)

API documentation

Update an object (or multiple objects) existing in GLPI.

>>> glpi.update('Computer',
                {'id': 5, 'otherserial': 'abcdef'})
>>> glpi.update('Computer',
                {'id': 5, 'otherserial': 'abcdef'},
                {'id': 6, 'otherserial': 'bcdefg'})
[{'5': True, 'message': ''}, {'6': True, 'message': ''}]

delete(itemtype, *items, **kwargs)

API documentation

Delete an object existing in GLPI.

# Move some computers to the trash.
>>> glpi.delete('Computer', {'id': 5}, {'id': 6})
[{'5': True, 'message': ''}, {'6': True, 'message': ''}]
# Purge computers.
>>> glpi.delete('Computer', {'id': 2}, {'id': 5}, force_purge=True)
[{'2': True, 'message': ''}, {'5': True, 'message': ''}]
# With non existing items
>>> glpi.delete('Computer', {'id': 2}, {'id': 101}, force_purge=True)
[{'2': True, 'message': ''}, {'101': False, 'message': 'Item not found'}]

upload_document(name, filepath)

API documentation

Upload the file at filepath as a document named name.

glpi.upload_document("My test document", '/path/to/file/locally')
{'id': 55,
 'message': 'Item successfully added: My test document',
 'upload_result': {'filename': [{'name': ...}]}}

There may be errors while uploading the file (like a non managed file type). In this case, the API create a document but without a file attached to it. This method raise a warning (and another warning if the document could not be deleted for some reasons) and purge the created but incomplete document.

download_document(doc_id, dirpath, filename=None)

API documentation

Download the file of the document with id doc_id in the directory dirpath. If filename is not set, the name of the file is retrieved from the server otherwise the given value is used. The local path of the file is returned by the method.

glpi.download_file(1, '/tmp')
/tmp/test.txt
glpi.download_file(1, '/tmp', filename='thenameiwant.txt')
/tmp/thenameiwant.txt