Adición de extremos no disponibles mediante una especificación de Swagger

Definición del modelo de ThingWorx en Composer > Modelado > Conectores de integración > Requisitos previos de conectores de integración > Utilización de ODataConnector o SAPODataConnector > Adición de extremos no disponibles mediante una especificación de Swagger

Por ejemplo, considere las siguientes definiciones de EntityType en una especificación OData:

El extremo que permite añadir PrimaryContent a un objeto Document dado no se incluye en la lista de extremos que ODataConnector genera a partir del análisis de la especificación OData. En general, los extremos que el sistema back-end soporta para las definiciones de NavigationProperty de un objeto EntityType no se incluyen en la lista que el conector genera. Por lo tanto, se debe crear una especificación de Swagger en la que se definan estos extremos y, a continuación, añadirla en formato JSON como el valor de la propiedad SwaggerJSON. Para obtener más información, consulte Utilización de ODataConnector o SAPODataConnector.

Para el ejemplo anterior, se sabe lo siguiente tras leer la especificación de OData:

• La ruta del extremo tendrá la forma /Documents('{ID}')/PrimaryContent, donde

◦ Documents es el nombre del objeto entitySet en el que se incluirán las entidades Document.

◦ ID es el objeto Key de un objeto Document que se utiliza para identificar una instancia de Document de manera exclusiva. Las llaves {} alrededor del objeto ID indican que se trata de un marcador para un parámetro de ruta obligatorio, que debería proporcionarse al realizar una solicitud reemplazando el marcador con el valor real.

◦ PrimaryContent es el objeto NavigationProperty de un objeto Document.

• PUT es la operación HTTP que soporta la carga de PrimaryContent para un objeto Document porque el objeto PrimaryContent es del tipo ContentItem. ContentItem tiene su propiedad HasStream definida en True.

• Un fichero que se debe cargar como PrimaryContent de un objeto Document es una entrada obligatoria, y el objeto ContentType de la solicitud debe ser multipart/form-data para que la solicitud se ejecute correctamente.

• La respuesta de la ejecución del extremo será una de las siguientes:

◦ Un objeto JSON cuyo esquema sigue correctamente a la definición de ContentItem.

◦ Un error que indica una solicitud no válida.

Antes de crear una especificación de Swagger para una solicitud, se deben evaluar todos los requisitos para ejecutar dicha solicitud en un extremo mediante una aplicación como, por ejemplo, la extensión Postman para Google Chrome.

Tras evaluar los requisitos en Postman, utilice una herramienta como, por ejemplo, Swagger Editor, para crear una definición para el extremo.

1. Inicie el editor con un objeto paths vacío.

2. Añada la ruta del extremo y la operación HTTP que la ruta soporta. En el ejemplo, anterior, "/Documents('{ID}')/PrimaryContent" y put, respectivamente.

3. Añada las definiciones de los parámetros de entrada de ID (parámetro path) y File (parámetro formData).

4. Añada la siguiente lógica para el extremo: consumes: [ multipart/form-data ], y produces: [ application/json ].

5. Añada respuestas identificadas por los códigos de estado HTTP que el extremo generará.

Por ejemplo:

◦ Una operación correcta (código de estado HTTP 200) devolverá un objeto JSON cuyo esquema sigue la definición de ContentItem. La referencia a la definición de ContentItem se indica a través de la propiedad $ref.

◦ Una solicitud no válida (código de estado HTTP 405).

6. Añada una definición de ContentItem. Para comprender el esquema, consulte la definición de entityType de ContentItem en la especificación de OData.

7. Proporcione un objeto operationId y summary para la operación PUT.

8. Una vez resueltos los errores registrados en el editor y de que se hayan añadido las rutas, las operaciones y las definiciones necesarias, exporte la especificación de Swagger como un fichero JSON.

9. Copie el contenido del fichero JSON exportado y defínalo como el valor de la propiedad SwaggerJSON.