API de exportación de datos: un recorrido por la API

Esto es parte de un serie sobre la exploración de la API de exportación de datos de SAP Analytics Cloud (SAC). Cuando la serie esté completa, también estará disponible como una sola misión tutorial.

hemos configuró nuestro arrendatario de SAP Analytics Cloud (SAC) para acomodar una aplicación. Ahora asumiremos el manto de esa aplicación y exploraremos el API de exportación. Asumiré que tiene un probador de API y sabe cómo usarlo. Puedes usar cualquiera que desees, pero yo usaré Cartero para los ejemplos. El proceso de obtener datos de un modelo implica, como mínimo, los siguientes pasos:

1. Obtener el token de autorización para la sesión
2. Enumere los «proveedores» (también conocidos como modelos)
3. Obtener los metadatos para el modelo específico de s
4. Obtenga los datos de auditoría, maestros y hechos para ese modelo, según lo desee

Token de autorización

Recuerde que cuando configuró su cliente OAuth en la pestaña Integración de aplicaciones de la administración de inquilinos, había cierta información que necesitaría usar más adelante. Específicamente, necesitarás:

1. 1. La URL del token de la descripción general de Integración de aplicaciones
      
   2. El ID de cliente y el secreto del cliente de OAuth individual
      

En Postman, varias llamadas de URL REST se agrupan en un recopilación y esta colección comparte un token de autorización. Si busca en la pestaña de autorización de su colección, puede ingresar esta información mediante copiar y pegar. Para obtener más información sobre la gestión de tokens de autorización en Postman, puede buscar en el SAP Help Portal para un ejemplo de OAuth y en el Postman Learning Center para documentación más completa.

El patrón de URL de la API de exportación

Todas las direcciones URL en la API de exportación de datos de SAC siguen un patrón similar de baseURL + extremo de servicio. La baseURL se construye como:

https://<tenantName>.<dataCenter>.sapanalytics.cloud/api/v1/dataexport

Entonces, si conoce el nombre de su inquilino y en qué centro de datos se encuentra, es fácil de construir. Para servicios individuales, agregará el fragmento de «punto final de servicio» de la URL para el servicio individual.

Todos los puntos finales de URL de servicio usan GET, no POST. En la práctica, esto significa que construirá cualquier parametrización en la propia cadena de URL, en lugar de un cuerpo json.

Puntos finales de URL del servicio de administración

Existen cuatro puntos finales del servicio de administración.

• /administración/Espacios de nombres
• /administration/Namespaces(NamespaceID=’sac’)
• /administración/$metadatos
• /administration/Namespaces(NamespaceID=’sac’)/Proveedores

Ninguno de los dos primeros puntos finales devuelve mucha importancia y están ahí para el cumplimiento de OData. Hay un único espacio de nombres (‘sac’) en la API de exportación, por lo que ambos devuelven lo mismo; el nombre y la descripción de este espacio de nombres, en formato json.

https://<tenant>.<datacenter>.sapanalytics.cloud/api/v1/dataexport/administration/Namespaces

devoluciones

{
    "@odata.context": "https://<tenant>.<datacenter>.sapanalytics.cloud/api/v1/dataexport/administration/$metadata#Namespaces",
    "value": [
    {
        "NamespaceID": "sac",
        "Description": "SAC Namespace"
    }
    ]
}

En Postman, esto se ve así:

/administración/$metadatos – este punto final devuelve la definición de esquema de la propia API, en formato XML; también conocido como la API OData EDMX. Si desea verlo en una herramienta OpenAPI, como Swagger, puede convertirlo. No lo vamos a usar, pero está disponible como una definición de API legible por máquina.

/administration/Namespaces(NamespaceID=’sac’)/Proveedores – Este punto final es importante. Proveedores es lo que SAC llama modelos en este contexto. Este punto final devuelve un json, que enumera todos los modelos en el arrendatario, junto con sus nombres, descripciones e ID de proveedor. Esto Id. de proveedor es el identificador interno de SAC para el modelo. Por lo general, este es un hash largo generado. Para ciertos modelos provistos por SAP, es legible por humanos. Por ejemplo, el ProviderID para el modelo de muestra Best Run Juice es sap.epm:BestRunJuice_SampleModel. Por último, el json contiene la URL del documento de servicio para cada modelo. Hablaremos del documento de servicio en la siguiente sección.

https://<tenant>.datacenter>.sapanalytics.cloud/api/v1/dataexport/administration/Namespaces(NamespaceID='sac')/Providers

Obtener los metadatos del modelo

Hay dos puntos finales de URL de servicio, que devuelven los metadatos de nuestro modelo.

• /proveedores/sac//
• /providers/sac//$metadatos

/proveedores/sac// devuelve el documento de servicio. El documento de servicio es una lista de los puntos finales de servicio disponibles para este proveedor. Estos puntos finales son:

• Los datos de auditoría
• Los datos maestros del modelo
• los datos de hecho
• Los datos maestros de cada dimensión

Por ejemplo, la URL del documento de servicio OData de Best Run Juice se ve así:

https://<tenant>.datacenter>.sapanalytics.cloud/api/v1/dataexport/providers/sac/sap.epm:BestRunJuice_SampleModel/

Y la respuesta json es:

{
    "@odata.context": "$metadata",
    "value": [
        {
            "name": "FactData",
            "url": "FactData"
        },
        {
            "name": "MasterData",
            "url": "MasterData"
        },
        {
            "name": "AuditData",
            "url": "AuditData"
        },
        {
            "name": "Account_BestRunJ_soldMaster",
            "url": "Account_BestRunJ_soldMaster"
        },
        {
            "name": "Store_3z2g5g06m4Master",
            "url": "Store_3z2g5g06m4Master"
        },
        {
            "name": "Location_4nm2e04531Master",
            "url": "Location_4nm2e04531Master"
        },
        {
            "name": "Product_3e315003anMaster",
            "url": "Product_3e315003anMaster"
        },
        {
            "name": "Sales_Manager__5w3m5d06b5Master",
            "url": "Sales_Manager__5w3m5d06b5Master"
        },
        {
            "name": "Date_703i1904sdMaster",
            "url": "Date_703i1904sdMaster"
        },
        {
            "name": "Version_BestRunJsold_VMaster",
            "url": "Version_BestRunJsold_VMaster"
        }
    ]
}

Por lo general, todos estos puntos finales específicos del proveedor devuelven su conjunto de datos completo (auditoría, maestro de dimensión o hecho) de forma predeterminada. Por lo tanto, el punto final de la tabla de hechos devolvería la tabla de hechos completa, los puntos finales de datos maestros de dimensión devolverían todos los valores de datos maestros, etc. Todos estos puntos finales admiten el parámetros típicos de ODatatal como $seleccionar, $filtro, $ordenarpor, $tamaño de página y $saltarlo que le permite dar forma a los datos devueltos json según sus necesidades.

/providers/sac//AuditData – Este punto final devuelve un (tal vez) pequeño json, que indica el número de entradas en el registro de auditoría y el propio registro de auditoría. Si la auditoría no se ha habilitado para el modelo, el punto final aún funciona; simplemente devuelve un registro de auditoría vacío.

por ejemplo, este modelo no ha habilitado la auditoría:

https://<tenant>.datacenter>sapanalytics.cloud/api/v1/dataexport/providers/sac/Cvjk1n1h4a6dr12dm10c07rr46o/AuditData

Todavía devuelve una respuesta json válida, pero puede ver que el registro de auditoría (valor) está vacío:

{
    "@odata.context": "https://<tenant>.<datacenter>.sapanalytics.cloud/api/v1/dataexport/providers/sac/Cvjk1n1h4a6dr12dm10c07rr46o/$metadata#AuditData",
    "value": [],
    "@des.entitiesInPage": "0",
    "@des.processingTimeInMilliseconds": "1040"
}

/providers/sac//$metadatos – Este es un punto final interesante, porque devuelve la definición completa de la API OData EDMX para ese modelo en particular. Examinando este jugoso documento, puede averiguar cuáles son sus medidas, dimensiones de cuenta, dimensiones de fecha, dimensiones genéricas, etc. Puede inclinarse por usar el documento de servicio como una vista de 10,000 pies de su modelo, porque es fácil de leer. , pero el documento EDMX es mucho más informativo.

Datos de hecho

proveedores/sac//FactData – Estos son los datos de hechos del modelo, devueltos en formato json. Como se mencionó anteriormente, a menos que lo filtre o pagine los resultados devueltos, será la tabla de hechos completa* (al menos hasta que Delta esté disponible con QRC 2023.Q1).

Si quisiera toda la tabla de hechos del modelo de muestra Best Run Juice, crearía su llamada http como tal:

https://<tenant>.datacenter>.sapanalytics.cloud/api/v1/dataexport/providers/sac/sap.epm:BestRunJuice_SampleModel/FactData

Pero si desea solo la cuenta Cantidad vendida y solo datos de hechos relacionados con el ID de producto PD1, puede agregar filtros OData:

https://<tenant>.datacenter>.sapanalytics.cloud/api/v1/dataexport/providers/sac/sap.epm:BestRunJuice_SampleModel/FactData?$filter=Account_BestRunJ_sold eq 'Quantity_sold' and Product_3e315003an eq 'PD1'

Datos maestros de dimensión

/providers/sac//Maestro – Este punto final devuelve un json con los datos maestros de la dimensión especificada. Por ejemplo, para una enumeración completa de la dimensión X, en el modelo Best Run Juice, crearía la siguiente URL:

https://<tenant>.datacenter>.sapanalytics.cloud/api/v1/dataexport/providers/sac/sap.epm:BestRunJuice_SampleModel/Product_3e315003anMaster

Esto concluye nuestro recorrido por la API de exportación de datos de SAC, a partir de enero de 2023. Tenemos planes activos para expandir esta API, por lo que se agregarán más puntos finales y funciones. La próxima vez, comenzaremos a construir un contenedor de Python.