Bienvenido a la documentación de la API de REST de Data360 Govern.
La información de esta sección se proporciona en conjunto con la documentación de la API de Swagger, en la que puede probar las consultas y ver los detalles de puntos de conexión específicos. Puede acceder a la documentación de Swagger desde la aplicación visitando .
La API de Data360 Govern le permite acceder a la aplicación a través de aplicaciones de terceros y le permite integrarse fácilmente con Data360 Analyze y Data360 DQ+.
Versiones
La API v1 ha quedado obsoleta y no se admitirá en futuras versiones. Utilice la API v2 cuando sea posible.
La aplicación se asegura a través de SNI (Server Name Indication). Debe utilizar la versión 7.18.1 o superior de SNI y, al menos, TLS 1.0.
Autenticación
Para autenticarlo, debe proporcionar sus credenciales de API en el encabezado de la solicitud en el siguiente formato:
<API Key>;<API Secret>
Obtención de las credenciales de API
Data360 Govern genera una clave de API y un secreto de API para cada usuario.
Puede obtener sus credenciales API de la siguiente manera:
- Iniciar sesión en Data360 Govern.
- En el menú Perfil en la parte superior derecha de la pantalla, seleccione Clave de API.
- Copie el valor del campo Clave de Api y guárdelo fuera de la aplicación.
- Copie el valor del campo Secreto de API y guárdelo fuera de la aplicación. Deberá utilizar estos valores para acceder a la API.
En algunos casos, por ejemplo en la integración con Data360 Analyze, las credenciales de API que se utilizan para conectar pueden ser las credenciales de una cuenta de servicio que se ha creado específicamente para su integración. En este caso, póngase en contacto con su representante de Precisely para obtener más información.
Hacer una solicitud
Una solicitud está compuesta de los siguientes elementos de información:
- Encabezados de solicitud: Proporcionan información al cliente y al servidor, incluidas las credenciales de autenticación y los formatos de datos aceptados.
- Método: Define el tipo de solicitud que se realizará (GET, POST, PUT y DELETE).
- Punto de conexión: Indica el modo en que se accede al recurso.
- Cuerpo: Se envía un cuerpo con solicitudes POST, PUT y DELETE que contiene información para que el servidor actúe, por ejemplo, nombre del objeto, campos y valores de campo.
Además, algunos puntos de conexión también contienen parámetros opcionales u obligatorios que se utilizan para personalizar más la respuesta de la API.
Encabezados de solicitudes
| Clave de encabezado | Descripción |
|---|---|
| Autorización |
Especifica las credenciales de autenticación: |
| Tipo de contenido |
Especifica el formato de los datos: |
| Aceptar |
Especifica el formato de datos aceptable para la respuesta: |
También puede utilizar un token de flujo de trabajo en el campo Valor del encabezado. Consulte Creación de un flujo de trabajo que llama a una API externa, Paso 2: configure la actividad de solicitud HTTP para obtener más información.
Métodos y puntos de conexión
Los puntos de conexión indican el modo en que se accede al recurso, y el método de solicitud HTTP define el tipo de solicitud que se va a realizar.
La API de Data360 Govern utiliza los siguientes métodos estándar para realizar solicitudes:
| Método | Acción |
|---|---|
| GET | Recupera recursos |
| POST | Crea recursos |
| PUT |
Actualiza los recursos existentes |
| DELETE | Elimina recursos |
En algunos casos, las solicitudes PUT también pueden utilizarse para crear recursos. Por ejemplo, el punto de conexión PUT api/v2/fields puede utilizarse para agregar o actualizar tipos de campos. Para ver los detalles de una solicitud PUT específica, consulte los detalles del resumen de punto de conexión en Swagger, por ejemplo:
Cada recurso tiene una variedad de puntos de conexión relacionados. El punto de conexión muestra la ruta de acceso de una URL de recursos, y la ruta de acceso base es común a todos los puntos de conexión, por ejemplo:
https://example.data3sixty.com/api/v2/assets/types
Cuerpo de la solicitud
En la IU de Swagger, cada método de la API que requiere un cuerpo de solicitud incluye una plantilla de ejemplo que se puede utilizar como punto de partida y modificar para satisfacer las necesidades de su solicitud.
Por ejemplo, el punto de conexión POST /api/v2/metrics/results tiene un cuerpo de solicitud obligatorio que le exige que haga referencia a un UID de activo y a un UID de activo de métrica:
[ { "AssetUid": "b1c4f830-c71c-4f95-909d-a1d67ca5361c", "MetricAssetUid": "d06f201c-4241-4102-8d68-07d4fb37dfc1", "EffectiveDate": "2019-05-08T08:51:56.737Z", "Result": true } ]En Swagger, el cuerpo de la solicitud se muestra de la siguiente manera:
Haga clic en la plantilla de ejemplo que se encuentra a la derecha de la pantalla para rellenar el parámetro del modelo a la izquierda; a continuación, introduzca los valores UID reales para reemplazar el texto del marcador de posición (00000000-0000-0000-0000-000000000000).
Debe incluir todos los campos obligatorios en el cuerpo de solicitud, por ejemplo, cuando cree un nuevo activo a través de una solicitud POST. Los campos opcionales se pueden eliminar si no hay ningún valor que enviar.
Para algunas solicitudes, por ejemplo, las solicitudes en lotes para grandes cantidades de datos, puede incluir un parámetro opcional para comprobar si se han agregado o actualizado los activos correctamente o han dado fallo.
Parámetros
Algunos puntos de conexión también contienen parámetros opcionales u obligatorios que se utilizan para personalizar más la respuesta de la API.
| Tipo de parámetro | Descripción | Ejemplo |
|---|---|---|
| Ruta | Parámetros que se incluyen dentro de la ruta del punto de conexión, generalmente entre llaves. |
El punto de conexión GET |
| Consulta | Parámetros que están incluidos en la cadena de consulta de un punto de conexión, después de un carácter "?". |
El punto de conexión GET |
Puede encontrar detalles de parámetros específicos en la página de documentación de la API de Swagger.
Solicitud de ejemplo
Las solicitudes de la API de ejemplo en esta sección de la ayuda utilizan la sintaxis Curl para mostrar toda la información requerida, como los encabezados, métodos, puntos de conexión y datos de la solicitud, así como cualquier parámetro opcional y obligatorio:
curl -X GET --header 'Accept: application/json' --header 'Authorization: key;secret' 'https://example.data3sixty.com/api/v2/assets/types' Curl proporciona una biblioteca y una herramienta de línea de comandos para transferir datos a los servidores mediante distintos protocolos estándar, como HTTPS.
El siguiente ejemplo muestra la información del encabezado para la misma solicitud para su uso al conectarse a la API de Data360 Govern a través de un cliente API:
GET https://example.data3sixty.com/api/v2/assets/types HTTP/1.1 Authorization: <API Key>;<API Secret> Content-Type: application/json Accept: application/jsonEvaluación de la respuesta
Códigos de respuesta
| Código de estado HTTP | Descripción | Solución de problemas |
|---|---|---|
| 200 |
Indica que se ha realizado correctamente. |
N/A |
| 400 |
Indica un error debido a una solicitud no válida. |
Compruebe que ha formateado correctamente el identificador (UID) en su solicitud. |
| 401 | Indica un error de autenticación. |
Compruebe que su encabezado de solicitud incluya las credenciales de autenticación requeridas. Si aún tiene problemas, puede ser que no tenga el permiso necesario para ver o editar el recurso en función de las responsabilidades que se le hayan asignado en la aplicación. |
| 403 | Indica un error de "acceso denegado". | Puede ser que no tenga el permiso necesario para ver o editar el recurso en función de las responsabilidades que se le hayan asignado en la aplicación. |
| 404 | Indica que no se ha encontrado el recurso solicitado. | Compruebe que ha formateado correctamente el identificador (UID) en su solicitud. |
| 406 | Indica que la solicitud no contiene el parámetro o los campos obligatorios. | Compruebe que ha incluido todos los tipos y campos de parámetros obligatorios. |
| 409 | Indica que el recurso solicitado ya existe. | N/A |
| 500 | Indica que se ha producido un error desconocido al procesar la solicitud. | N/A |
Respuesta de ejemplo
HTTP/1.1 200 OK "content-length": "2", "content-type": "application/json; charset=utf-8" [ { "uid": "85315000-c77f-4898-84db-f4872cbd2dc0", "Name": "Bloomberg", "Description": "Metadata via the Bloomberg Fields CSV file and other Bloomberg sources.", "Class": { "ID": 3, "Name": "Technical Asset", "Description": "Technical assets." }, "Path": "Bloomberg" }, { "uid": "88e6e59c-0cd8-49a9-a4f4-059b7172ddee", "Name": "Business Calendar", "Class": { "ID": 4, "Name": "Technical Asset", "Description": "Technical assets." }, "Path": "Business Calendar" } ]Casos de uso común
La API de Data360 Govern le permite obtener información sobre los activos de su aplicación de gobierno de datos.
Los casos de uso habituales incluyen:
- Obtener información sobre los activos existentes en su sistema de gobierno de datos, como los detalles de las relaciones y la propiedad.
- Agregar metadatos técnicos de fuentes de datos externas para dar contexto a sus activos empresariales.
- Aplicar puntuación a sus activos de gobierno de datos (consulte Uso de la API para aplicar puntuación a sus activos).
- Promover los activos técnicos a su glosario empresarial.
Consejos y sugerencias
| Consejo | Descripción |
|---|---|
|
Puntos de conexión para el procesamiento por lotes |
Cuando se trabaja con una gran cantidad de elementos, se recomienda utilizar los puntos de conexión "de lote". Donde hay un punto de conexión "de lote", el equivalente "sin lote" a menudo tiene un límite de 250 elementos. Los puntos de conexión "de lote" están diseñados para un mayor número de elementos, ya que almacenan la lista de elementos para un procesamiento asincrónico o por lotes. Por ejemplo, puede utilizar los siguientes puntos de conexión para eliminar un conjunto de activos basados en el identificador único del tipo de activo especificado. El primero está destinado a un número menor de elementos y el segundo está destinado a procesar un número mayor de elementos:
Nota: Se recomienda no utilizar la IU de Swagger para solicitudes de gran tamaño. Para manejar solicitudes más grandes, se recomienda utilizar un cliente API alternativo.
Nota: Cada entorno está limitado a dos solicitudes por lotes a la vez.
Nota: No se garantiza que el orden de ejecución de las llamadas de la API por lotes sea el orden en el que se enviaron los trabajos. Por ejemplo, si envía diez trabajos por lotes en un periodo de treinta segundos, los trabajos no se ejecutarán necesariamente en el orden en el que se enviaron.
|
|
Tamaño de página |
No hay un tamaño de página máximo. Sin embargo, se recomienda restringir el tamaño de página según el tamaño de su consulta. Por ejemplo, al usar el punto de conexión GET Puede utilizar el parámetro |
|
Propiedades de JSON |
Debido a la forma en la que el serializador JSON maneja los datos, si el valor es nulo, no hay garantías de que se muestre la propiedad. Del mismo modo, el orden de las propiedades que se devuelven no siempre es el mismo. |
|
Encabezado de X-HTTP-Method-Override |
Para evitar realizar una solicitud POST con un cuerpo, puede utilizar |
|
Campos de claves de activos |
Cuando ejecuta una actualización (una solicitud PUT), la API busca todos los valores clave del campo, mediante el UID del activo suministrado. Recibirá un error si el tipo de activo especificado tiene un campo clave definido y hay activos con un valor NULO para este campo. |
|
Vínculos de activos |
Se puede acceder a cualquier activo en el siguiente vínculo, donde Por ejemplo: Puede acceder a la página de lista de tipos de activos para activos empresariales, activos técnicos, activos de modelos o activos de reglas en el siguiente vínculo, donde Por ejemplo: |