Buscar en la base de conocimiento

Definir un esquema para un servicio externo

Link de trailhead

Objetivos de aprendizaje

Después de completar esta unidad, podrá:

  • Describir la finalidad de la definición de esquema.
  • Explicar los elementos de una buena definición de esquema de servicios externos.
  • Indicar tres problemas que pueden generar un error en su esquema.

¿Para qué es útil un esquema?

Con independencia de que sea o no quien finalmente define un esquema para su registro de servicios externos, sirve de ayuda comprender para qué es útil y cómo se utiliza. Si ya está familiarizado con la definición de un esquema de una API basada en REST, puede pasar a la siguiente sección: Además... ¿cómo es un buen esquema?

Empecemos por la especificación del esquema, que es la API basada en REST que procede de un proveedor de servicios externos (por ejemplo, un banco). Como mencionamos en la unidad anterior, puede considerar la especificación como un contrato. El motivo es que contiene los tipos de entradas y salidas que puede incluir en las llamadas o solicitudes que su organización realiza para el servicio externo. Por ejemplo, sus llamadas podrían incluir un Id. como entrada numérica o un nombre como salida de texto.

Además, contiene la información de extremo y los parámetros de autenticación para los servicios web de la API basada en REST a los que puede acceder. (Recuerde que el extremo expone los recursos de servicios web con los que interactúan los servicios externos). Por ejemplo, este extremo de un banco ficticio incluye métodos para agregar y eliminar cuentas. https://th-external-services.herokuapp.com/accounts/schema

Nota

¡Lo normal es que realice un paso de autenticación antes de acceder a la API de un banco!

Por otra parte, la definición de esquema consta de datos estructurados legibles para el ser humano. Veamos este esquema en su conjunto. Este miniprograma de la definición de esquema contiene información sobre un método GET. Por si no lo sabía, un método GET simplemente recupera información de los recursos de un servicio. Este método GET en concreto recupera (“obtiene”) información sobre una cuenta mediante la ruta del recurso (en este caso, /accounts/{accountName}), donde {accountName} es una cuenta especificada. Si mira debajo de “parameters”, puede ver "name":"accountName". Este parámetro debe coincidir con el nombre de la cuenta que especifique y es obligatorio ("required":true). Además, debe tener la forma de una cadena.


   "paths":{  
      "/accounts/{accountName}":{  
         "get":{  
            "operationId":"getAccount",
            "summary":"Retrieves an account",
            "description":"Retrieves the account with specific name",
            "consumes":[  
               "text/plain"
            ],
            "produces":[  
               "application/json"
            ],
            "parameters":[  
               {  
                  "name":"accountName",
                  "in":"path",
                  "required":true,
                  "type":"string",
                  "description":"Name of the account"
               }
            ],
            "responses":{  
               "200":{  
                  "description":"The response when system finds an account with given name",
                  "schema":{  
                     "$ref":"#/definitions/accountDetails"
                  }
               },
               ....
Por supuesto, el esquema incluye mucho más. No obstante, puede observar que aunque está diseñado para el consumo por parte de los servicios externos, es sin duda legible para el ser humano. Esto se debe a que tiene un formato lógico que permite a los servicios externos procesar los datos de modo que puedan generar acciones de Apex. Estas acciones de Apex son las que utilizamos posteriormente como entradas y salidas en un flujo.

Los pasos siguientes le permiten utilizar herramientas declarativas para registrar su servicio. Pero en primer lugar, vamos a examinar los elementos que componen una definición de esquema de utilidad.

Además... ¿cómo es un buen esquema?

Veamos. Ya sabemos para qué es útil un esquema, o para ser más precisos, una definición de esquema. Pero, ¿qué convierte en útil una definición de esquema? Además, ¿podría ser algo realmente negativo?

Sí, en realidad un esquema puede ser negativo. Aunque un esquema es legible para el ser humano, además requiere una estructura lógica que permita que los servicios externos lo consuman. Si un esquema no está estructurado correctamente, el servicio externo devuelve mensajes de error y excepción. Por lo tanto, veamos qué es lo esencial para que un esquema sea óptimo con el fin de garantizar que nuestro flujo pueda consumir correctamente clases de Apex generadas por los servicios externos. Al crear un esquema, debemos asegurarnos de lo siguiente:
  • Los esquemas incluyen hasta 100.000 caracteres, pero no más.
  • No se utilizan nombres reservados.
  • Solo se incluyen métodos admitidos.
  • Las propiedades incluyen valores.
  • Los parámetros tienen nombres.
  • La salida del código de respuesta no contiene objetos complejos.
Además, utilizamos el hiperesquema Interagent mediante JSON o Swagger Open API 2.0.

Sugerencia

Si utiliza Swagger, puede utilizar el editor de Swagger para validar que su esquema cumple con la especificación de Swagger. Si desea desviarse para abreviar, continúe y copie el esquema de https://th-external-services.herokuapp.com/accounts/schema en el editor de Swagger. No debería recibir ningún error.

Ya están revisados algunos conceptos sobre los esquemas y además algunos requisitos. ¿Desea profundizar y ponerse manos a la obra con los servicios externos? ¡Por supuesto que sí! Eso es lo que haremos en la siguiente unidad. Sin embargo, antes de avanzar, vamos a ver los dos primeros pasos que examinamos en la primera unidad.
  1. Un proveedor de servicios externos (por ejemplo, un banco) comparte su especificación de esquema de la API basada en REST. Recibimos esta información de nuestro banco ficticio.
  2. De acuerdo con la especificación, un desarrollador (o incluso usted) crea una definición de esquema que describe la API. Aunque nosotros no creamos este esquema, revisamos los elementos de un esquema y los requisitos que debe cumplir un buen esquema. Cuando trabaje con servicios externos, usted o su desarrollador pueden definir el esquema que necesita para su caso de uso.

¿Le ha resultado útil este artículo?


Articulos relacionados