Ajout de points de terminaison non disponibles à l'aide d'une spécification Swagger

Définition du modèle ThingWorx dans Composer > Modélisation > Connecteurs d'intégration > Prérequis pour les connecteurs d'intégration > Utilisation d'ODataConnector ou de SAPODataConnector > Ajout de points de terminaison non disponibles à l'aide d'une spécification Swagger

Prenons, par exemple, les définitions d'EntityType suivantes dans une spécification OData :

Le point de terminaison qui permet d'ajouter PrimaryContent à un Document donné n'est pas inclus dans la liste de points de terminaison qu'ODataConnector génère à partir de l'analyse de la spécification OData. En général, les points de terminaison pris en charge par le système principal pour les définitions de NavigationProperty d'un EntityType ne sont pas inclus dans la liste générée par le connecteur. Par conséquent, vous devez créer une spécification Swagger qui définit ces points de terminaison, puis ajouter la spécification au format JSON comme valeur de la propriété SwaggerJSON. Pour en savoir plus, consultez la rubrique Utilisation d'ODataConnector ou de SAPODataConnector.

Dans l'exemple ci-dessus, la spécification OData nous apprend les éléments suivants :

• Le chemin d'accès au point de terminaison est de forme /Documents('{ID}')/PrimaryContent, où :

◦ Documents est le nom d'entitySet qui contiendra les entités Document.

◦ ID est la propriété Key d'un Document qui est utilisée pour identifier de manière unique une instance de Document. Les crochets {} autour ID indiquent qu'il s'agit d'un espace réservé à un paramètre de chemin obligatoire, qui doit être fourni lors d'une demande en remplaçant l'espace réservé par la valeur réelle.

◦ PrimaryContent est la NavigationProperty d'un Document.

• PUT est l'opération HTTP qui prend en charge le chargement du PrimaryContent d'un Document si le PrimaryContent est de type ContentItem. ContentItem a sa propriété HasStream définie sur True.

• Un fichier qui doit être chargé comme PrimaryContent d'un Document est une entrée requise, et le ContentType de la demande doit être multipart/form-data pour que l'exécution de la demande aboutisse.

• La réponse de l'exécution du point de terminaison sera l'une de celles-ci :

◦ Un objet JSON dont le schéma est conforme à la définition de ContentItem.

◦ Une erreur indiquant une demande non valide.

Toutes les exigences d'exécution d'une demande sur le point de terminaison doivent être évaluées à l'aide d'une application telle que l'extension Postman pour Google Chrome avant de créer une définition de spécification Swagger.

Après avoir évalué les exigences dans Postman, utilisez un outil tel que Swagger Editor pour créer une définition pour le point de terminaison.

1. Démarrez l'éditeur avec un objet paths vide.

2. Ajoutez le chemin du point de terminaison et l'opération HTTP que le chemin prend en charge. Dans l'exemple ci-dessus, il s'agit respectivement de "/Documents('{ID}')/PrimaryContent" et put.

3. Ajoutez les définitions de paramètre d'entrée pour ID (paramètre path) et pour File (paramètre formData).

4. Ajoutez la logique suivante pour le point de terminaison : consumes: [ multipart/form-data ], et produces: [ application/json ].

5. Ajoutez les réponses identifiées par les codes de statut HTTP que le point de terminaison générera.

Par exemple :

◦ Une opération réussie (code de statut HTTP 200) renverra un objet JSON dont le schéma est conforme à la définition de ContentItem. Nous indiquons la référence à la définition de ContentItem grâce à la propriété $ref.

◦ Une demande non valide (code de statut HTTP 405).

6. Ajoutez une définition de ContentItem. Reportez-vous à la définition d'entityType ContentItem dans la spécification OData pour comprendre le schéma.

7. Indiquez un ID d'opération et un résumé pour l'opération PUT.

8. Une fois que vous avez résolu les erreurs signalées dans l'éditeur et que les chemins, opérations et définitions nécessaires ont été ajoutés, exportez la spécification Swagger sous la forme d'un fichier JSON.

9. Copiez le contenu du fichier JSON exporté, puis définissez-le comme valeur de la propriété SwaggerJSON.