Ecriture de scripts avec l'API REST d'ArcGIS

L'administration de Portal for ArcGIS peut s'effectuer exclusivement par l'intermédiaire de demandes adressées à l'API REST d'ArcGIS. Même lorsque vous utilisez le site Web Portal for ArcGIS pour administrer votre portail, des appels sont adressés à l'API sur le serveur principal. Pour rédiger des scripts qui administrent Portal for ArcGIS, vous devez choisir un langage de script permettant de créer des URL, d'élaborer des requêtes HTTP et d'analyser les réponses HTTP. Les exemples utilisés dans ce système d'aide font appel au langage Python.

Il est important de noter que l'utilisation de l'API ne nécessite aucun logiciel Esri sur la machine à partir de laquelle vous exécutez le script. Vous avez simplement besoin d'un environnement dans lequel il est possible d'adresser des requêtes HTTP à votre portail.

Prise en main de l'administration du portail avec l'API REST d'ArcGIS

Pour utiliser l'API REST d'ArcGIS, vous devez créer une requête HTTP pour l'opération que vous souhaitez effectuer et inclure les paramètres requis pour cette opération. L'utilisation du répertoire Portal for ArcGIS constitue une méthode simple pour vous familiariser avec les opérations d'administration disponibles et leurs paramètres requis.

Utilisation du répertoire Portal for ArcGIS

Le répertoire Portal for ArcGIS est disponible via deux applications Web et peut vous aider à rédiger des scripts d'administration pour votre portail. Il est semblable, dans son concept, au répertoire administrateur et au répertoire des services d'ArcGIS for Server. Les tâches disponibles varient entre les applications, comme cela est décrit dans la rubrique A propos du répertoire Portal for ArcGIS. Les URL permettant d'accéder aux applications ont le format suivant :

• https://webadaptor.domain.com/arcgis/portaladmin
• https://webadaptor.domain.com/arcgis/sharing/rest

Considérez le répertoire Portal for ArcGIS comme une liste de ressources Portal for ArcGIS exposées par l'intermédiaire de l'API REST. Vous pouvez suivre les liens dans le répertoire Portal for ArcGIS pour connaître les URL et les paramètres à utiliser dans vos demandes de services Web administratives. Vous pouvez ensuite formuler ces demandes et les envoyer via le protocole HTTP à l'aide du langage de script de votre choix.

Essayez d'utiliser le répertoire Portal for ArcGIS pour effectuer une tâche d'administration. Prenez note des paramètres que vous êtes invité à saisir et examinez l'URL indiquée dans la barre d'adresse du navigateur lorsque vous effectuez la demande auprès du serveur. Les outils de développement Web, tels que Fiddler ou Firebug, peuvent se révéler utiles pour visualiser tout le contenu de la demande et de la réponse. Ces informations s'avèrent extrêmement précieuses lorsque vous tentez de créer vos propres demandes HTTP d'administration à l'aide de Python ou d'un autre langage de script.

Bien que vous puissiez utiliser le répertoire Portal for ArcGIS de manière interactive pour effectuer des tâches administratives, il est préférable de l'utiliser comme outil d'apprentissage pour vous familiariser avec l'API REST. L'application Web prévue pour l'administration du portail est le site Web Portal for ArcGIS.

Obtention et utilisation d'un jeton dans des scripts

Lorsque vous administrez le portail via son site Web ou le répertoire Portal for ArcGIS, vous devez indiquer le nom d'utilisateur et le mot de passe d'un compte détenteur des privilèges appropriés sur le portail. Le même concept est d'application lors de l'écriture de scripts.

Toutefois, vous devez comprendre le processus d'authentification lorsque vous utilisez des scripts pour administrer votre portail, car lorsque vous accédez au site Web ou au répertoire Portal for ArcGIS, c'est le navigateur qui gère en transparence le processus d'authentification.

Si votre portail est configuré pour utiliser des comptes intégrés et l'authentification à base de jetons, vous pourrez utiliser vos scripts avec les mêmes comptes administratifs et URL que vous utilisez à partir du répertoire Portal for ArcGIS. Si votre portail est configuré avec des identifiants de connexion d'entreprise et une authentification au niveau du Web, nous vous conseillons de faire en sorte que vos scripts ignorent l'adaptateur Web et utilisent le compte d'administrateur initial créé après l'installation de Portal for ArcGIS.

Dans les deux cas, le portail vous renvoie un jeton constitué d'une chaîne de caractères spécifique indiquant au portail auprès duquel vous vous êtes authentifié qu'il doit exécuter certains types d'opérations. Vous devez inclure ce jeton dans toute demande de service Web adressée au portail.

La fonction Python ci-dessous demande un jeton. L'URL du portail, le nom d'utilisateur et le mot de passe sont fournis comme arguments.

def generateToken(username, password, portalUrl):
    '''Retrieves a token to be used with API requests.'''
    parameters = urllib.urlencode({'username' : username,
                                   'password' : password,
                                   'client' : 'referer',
                                   'referer': portalUrl,
                                   'expiration': 60,
                                   'f' : 'json'})
    response = urllib.urlopen(portalUrl + '/sharing/rest/generateToken?',
                              parameters).read()
    try:
        jsonResponse = json.loads(response)
        if 'token' in jsonResponse:
            return jsonResponse['token']
        elif 'error' in jsonResponse:
            print jsonResponse['error']['message']
            for detail in jsonResponse['error']['details']:
                print detail
    except ValueError, e:
        print 'An unspecified error occurred.'
        print e

La durée du jeton est limitée pour éviter qu'il ne soit volé ou utilisé indéfiniment par un utilisateur malintentionné. Habituellement, vous devez demander un nouveau jeton à chaque exécution de votre script (mais pas chaque fois que vous effectuez une demande). Dans certains cas exceptionnels, les jetons peuvent expirer avant la fin de l'exécution de votre script. Si votre requête comprend un jeton qui a expiré, la réponse du serveur est accompagnée d'une erreur qui vous le signale. Dans ce cas, actualisez votre jeton et poursuivez l'exécution de votre script.

Utilisation de demandes et de réponses

Pour effectuer une demande de service Web, vous devez formuler l'URL pour l'action à réaliser, ainsi que les paramètres requis qui lui sont associés. L'un des paramètres requis sur un portail sécurisé est un jeton semblable à celui généré ci-dessus.

Toutes les tâches administratives génèrent une réponse de service Web, laquelle fait généralement l'objet d'une demande au format JSON (JavaScript Object Notation). Les langages de script tels que Python contiennent des bibliothèques capables d'analyser, ou de lire, une réponse JSON. Dans certains cas, vous souhaitez simplement obtenir le code d'état HTTP afin de déterminer si votre demande a abouti (le code 200, par exemple, signifie une réussite). Parfois, il se peut que la réponse comporte des données, telles que des messages de consignation, que vous souhaitez soumettre à une analyse plus approfondie.

Reportez-vous aux différents exemples de code de ce manuel pour bien comprendre comment envoyer, par programmation, une demande à Portal for ArcGIS et traiter une réponse.