Requisitos previos: tres elementos esenciales

Antes de llamar a cualquier API de Data Service, debe cumplir con tres requisitos previos:

La relación entre estos tres elementos es la siguiente: la API es la "puerta", la aplicación es la "credencial de identificación" y la autorización es el "pase". Solo podrá cruzar la puerta si presenta tanto una credencial de identificación válida como el pase correspondiente.

Crear una aplicación (identidad de la aplicación)

Una aplicación funciona como contenedor de las credenciales de llamada a la API. Cada aplicación cuenta con un conjunto independiente de información de autenticación (AppKey, AppSecret y AppCode), equivalente a una cuenta y contraseña.

Aplicación predeterminada creada automáticamente

Cuando publica una API en DataWorks por primera vez, el sistema crea automáticamente una aplicación con el mismo nombre que el espacio de trabajo en API Gateway y autoriza todas las APIs de ese espacio de trabajo para esta aplicación predeterminada. Esto significa que:

• Los miembros del espacio de trabajo pueden usar las credenciales de la aplicación predeterminada para llamar a las APIs sin necesidad de autorización adicional.

• La información de autenticación de la aplicación predeterminada se puede consultar en la página Call APIs de la consola de Data Service.

Crear una aplicación manualmente

Para aislar el tráfico o diferenciar permisos entre distintos llamadores, cree una nueva aplicación en la consola de API Gateway:

1. Inicie sesión en la consola de API Gateway.

2. En el panel de navegación izquierdo, seleccione Application Management.

3. Haga clic en Create Application e introduzca el nombre y la descripción de la aplicación.

4. Una vez creada la aplicación, el sistema genera un conjunto de AppKey, AppSecret y AppCode para dicha aplicación.

Cree aplicaciones separadas para diferentes escenarios de llamada (como sistemas internos, socios externos y paneles de control) para simplificar el monitoreo del tráfico, la limitación de velocidad y la gestión de permisos.

Proceso de autorización

La autorización otorga a una aplicación el permiso para llamar a una API específica. Solo una aplicación autorizada puede llamar correctamente a la API correspondiente utilizando sus credenciales.

Conceder acceso a otras cuentas

Para que una API esté disponible en espacios de trabajo bajo otras cuentas de Alibaba Cloud, realice una autorización entre cuentas:

1. Inicie sesión en la consola de DataWorks. En la región objetivo, haga clic en Data Analysis and Service > DataService Studio en el panel de navegación izquierdo. Seleccione un espacio de trabajo de la lista desplegable y haga clic en Go to DataService Studio.

2. Vaya a la página Data Services, haga clic en Service Management en la barra de menú superior y acceda a la página Manage APIs.

3. En la pestaña Published APIs, busque la API objetivo y haga clic en Authorization en la columna Actions.

4. En el cuadro de diálogo API Authorization, configure los siguientes parámetros:

   

   Parámetro	Descripción
   API Name	El nombre de la API que se va a autorizar. Este valor no se puede modificar.
   Alibaba Cloud Account ID to Authorize	El ID de la cuenta de Alibaba Cloud al que se le debe otorgar el permiso para llamar a esta API. Puede consultar el ID de la cuenta en la página .
   Authorized Workspace	Seleccione el espacio de trabajo bajo la cuenta de Alibaba Cloud objetivo.
   Authorization Validity Period	Seleccione el periodo de validez de la autorización (consulte los detalles a continuación).

5. Haga clic en Confirm para completar la autorización.

Periodo de validez de la autorización

El periodo de validez de la autorización determina durante cuánto tiempo la parte autorizada puede llamar a la API:

Si una API autorizada se retira o se elimina, la parte autorizada ya no podrá llamarla. Si una API autorizada se retira y luego se vuelve a publicar, o se modifica y se vuelve a publicar, el propietario de la API debe volver a autorizar la nueva versión.

Consultar APIs autorizadas y concedidas

En la página Manage APIs, puede consultar el estado de autorización desde dos perspectivas:

Consultar APIs autorizadas para usted (a qué APIs tengo autorización de uso)

Haga clic en la pestaña Authorized to Use para ver todas las APIs que otras cuentas le han autorizado. En esta página, puede:

• Hacer clic en Test para probar una API autorizada en línea. Para obtener más información, consulte Test an API.

• Hacer clic en Delete para renunciar voluntariamente a la autorización de llamada de una API.

Consultar APIs que ha autorizado a otros (qué APIs he autorizado a otros)

Haga clic en la pestaña Authorize Others to Use para ver las APIs que ha autorizado a otros espacios de trabajo. En esta página, puede:

• Hacer clic en Test para probar una API autorizada en línea.

• Hacer clic en Manage para revocar o modificar la autorización de un espacio de trabajo específico.

Tres escenarios de autorización

La granularidad de la autorización de API varía según el tamaño del equipo y los requisitos de seguridad. Los siguientes tres escenarios cubren los enfoques más comunes.

Escenario 1: Mismo espacio de trabajo, compartiendo una aplicación

Descripción del escenario: Todos los miembros dentro del mismo espacio de trabajo de DataWorks comparten la aplicación predeterminada que se creó automáticamente para el espacio de trabajo con el fin de llamar a las APIs.

Situación aplicable: Equipo pequeño con alta confianza mutua; no hay necesidad de diferenciar el tráfico de llamadas por miembro individual; inicio rápido con configuración mínima.

Funcionamiento: Cuando se publica una API, DataWorks crea automáticamente una aplicación con el mismo nombre que el espacio de trabajo y autoriza todas las APIs del espacio de trabajo para esta aplicación. Todos los miembros del espacio de trabajo comparten la misma AppKey, AppSecret y AppCode.

Ventaja: Configuración nula, listo para usar de inmediato. Desventaja: No se puede identificar qué miembro específico inició una llamada; si las credenciales se filtran, todo el espacio de trabajo se ve afectado.

Escenario 2: Cada usuario RAM usa una aplicación independiente

Descripción del escenario: Cada usuario RAM (subcuenta) en la organización crea una aplicación independiente en API Gateway y recibe autorización individual para llamar a las APIs.

Situación aplicable: Necesidad de rastrear con precisión el comportamiento de llamada a la API de cada usuario; necesidad de establecer diferentes políticas de limitación de velocidad para diferentes usuarios; altos requisitos de seguridad y cumplimiento que exigen credenciales por usuario.

Funcionamiento: Cada usuario RAM inicia sesión en la consola de API Gateway y crea su propia aplicación; el administrador de API autoriza la API para la aplicación de cada usuario individualmente; cada usuario llama a la API utilizando las credenciales de su propia aplicación.

Ventaja: El comportamiento de llamada es rastreable a nivel individual, fuerte aislamiento de seguridad e impacto mínimo por filtración de credenciales. Desventaja: Mayor sobrecarga de gestión; cada nuevo usuario requiere la creación de una aplicación y la configuración de autorización.

Escenario 3: Múltiples usuarios RAM agrupados, cada grupo comparte una aplicación

Descripción del escenario: Varios usuarios RAM se dividen en grupos por función empresarial o equipo, y los miembros dentro de cada grupo comparten la misma aplicación para llamar a las APIs.

Situación aplicable: Equipo grande organizado por departamento o proyecto; necesidad de diferenciar el tráfico de llamadas por línea de negocio sin requerir seguimiento por usuario; equilibrio entre costo de gestión y seguridad.

Funcionamiento: Cree un número correspondiente de aplicaciones para cada grupo empresarial; el administrador de API autoriza la API para la aplicación de cada grupo; los miembros dentro de un grupo comparten las credenciales de la aplicación de su grupo.

Ventaja: Granularidad de gestión moderada que distingue las fuentes de negocio sin una sobrecarga excesiva. Desventaja: No se pueden diferenciar aún más los miembros dentro del mismo grupo.

Recomendaciones para la selección de escenarios

Tres tipos de credenciales: evite confusiones

Data Service utiliza tres tipos distintos de credenciales de autenticación con diferentes propósitos, orígenes y escenarios de uso. Asegúrese de distinguirlas:

Resumen rápido: AccessKey sirve para "conectarse a fuentes de datos", AppKey para "llamar a APIs" y RAM para "acceder a la consola". Cada uno cumple un propósito diferente y no pueden sustituirse entre sí.

Confusión 1: "Mi llamada a API devuelve 403, pero tengo permisos de administrador RAM" — Los permisos RAM controlan las operaciones en la consola de DataWorks, no los permisos de llamada a la API. Los permisos de llamada a la API se controlan mediante la autorización de la aplicación. Incluso si es administrador RAM, todavía necesita la AppKey/AppSecret de una aplicación autorizada para llamar a una API.

Confusión 2: "¿La AccessKey configurada para la fuente de datos es la misma que la AppKey para las llamadas a API?" — No. La AccessKey la utiliza Data Service para conectarse a fuentes de datos backend; la AppKey la utilizan los llamadores para invocar APIs. Son completamente independientes.

Confusión 3: ¿Qué debo introducir en el campo "Alibaba Cloud Account ID" en la página de autorización? — La página de autorización requiere el ID de cuenta de Alibaba Cloud (un valor numérico), no un nombre de usuario RAM ni un correo electrónico de inicio de sesión. Para obtenerlo, inicie sesión en la página Account Management y consulte el ID de cuenta en la configuración de seguridad.

Comparación de métodos de autenticación

API Gateway admite dos métodos de autenticación. Data Service añade "autenticación APP de Alibaba Cloud" a las APIs del espacio de trabajo de forma predeterminada. Elija un método según sus requisitos de seguridad.

Autenticación simple (AppCode)

Añada el AppCode al encabezado de la solicitud HTTP para completar la autenticación. No se requiere cálculo de firma.

Ejemplo de solicitud:

GET /api/v1/users?name=test HTTP/1.1
Host: your-api-endpoint.cn-shanghai.alicloudapi.com
Authorization: APPCODE 3f963a8e1cd7492bbd8a5e2e5e4c****

Autenticación por firma (AppKey + AppSecret)

El llamador usa AppSecret para calcular una firma HMAC-SHA256 sobre el contenido de la solicitud y añade la AppKey y la firma al encabezado de la solicitud. API Gateway recalcula la firma usando la misma AppSecret y la compara para verificar la identidad del llamador.

Ejemplo de solicitud (sección de encabezado):

X-Ca-Key: 12345678
X-Ca-Signature: BASE64_ENCODED_SIGNATURE
X-Ca-Timestamp: 1741593600000
X-Ca-Nonce: unique-uuid-string
X-Ca-Signature-Headers: X-Ca-Key,X-Ca-Nonce,X-Ca-Timestamp

Comparación de los dos métodos

Recomendaciones de selección:

• Fase de desarrollo y pruebas: Use AppCode para una verificación rápida de la API y reducir costos de desarrollo.

• Entorno de producción: Utilice siempre autenticación por firma con AppKey + AppSecret y cifrado de transporte HTTPS.

• APIs expuestas externamente: Debe usar autenticación por firma para evitar ataques de repetición tras la interceptación de credenciales durante la transmisión.

Detalles del algoritmo de firma

La autenticación por firma se basa en el algoritmo HMAC-SHA256. El proceso principal es el siguiente:

Resumen del proceso de firma

1. Construir la cadena de solicitud canónica (StringToSign): Concatene en secuencia el método HTTP (GET/POST), el encabezado Accept, Content-MD5 (valor MD5 del cuerpo de la solicitud), Content-Type, Date, los encabezados personalizados involucrados en la firma (X-Ca-*, ordenados alfabéticamente) y la URL canónica (ruta + parámetros de consulta ordenados).

2. Calcular la firma usando HMAC-SHA256: Firma = Base64(HMAC-SHA256(AppSecret, StringToSign))

3. Añadir la información de firma al encabezado de la solicitud: Esto incluye X-Ca-Key (AppKey), X-Ca-Signature (valor de la firma), X-Ca-Timestamp (marca de tiempo en milisegundos), X-Ca-Nonce (UUID para evitar repeticiones) y X-Ca-Signature-Headers (lista de encabezados involucrados en la firma).

Consideraciones clave

Los siguientes detalles son fuentes comunes de errores de firma:

• Ordenamiento de parámetros: Los parámetros de consulta de URL y los encabezados de firma deben ordenarse por clave en orden alfabético (orden ASCII).

• Codificación URL: Los caracteres especiales en los valores de los parámetros (espacios, caracteres chinos, etc.) deben codificarse en URL.

• Separador de líneas: Las líneas en StringToSign deben separarse con \n (LF). No use \r\n (CRLF).

• Manejo de valores vacíos: Cuando no hay cuerpo, Content-MD5 es una cadena vacía (no null). Cuando encabezados como Accept no existen, use también una cadena vacía.

• Precisión de la marca de tiempo: X-Ca-Timestamp es una marca de tiempo en milisegundos. La diferencia horaria entre el cliente y el servidor no debe exceder los 15 minutos.

• Unicidad del Nonce: Se debe generar un UUID único para cada solicitud como X-Ca-Nonce. Reutilizar un nonce activa la interceptación por ataque de repetición.

Para ejemplos de código completos en Java y Python, reglas detalladas de concatenación de StringToSign y métodos de depuración para errores de firma comunes, consulte la sección Signature algorithm en la documentación de API Gateway.

Consultar credenciales de autenticación

Después de crear una aplicación y obtener la autorización, recupere la AppKey, AppSecret o AppCode para realizar llamadas a la API.

Consultar credenciales desde la consola de Data Service

1. Inicie sesión en la consola de DataWorks. En la región objetivo, haga clic en Data Analysis and Service > DataService Studio en el panel de navegación izquierdo. Seleccione un espacio de trabajo de la lista desplegable y haga clic en Go to DataService Studio.

2. En la página Data Service, haga clic en Service Management en la barra de menú superior.

3. En el panel de navegación izquierdo, haga clic en Call APIs.

4. En la página Call APIs, puede consultar y copiar la siguiente información de autenticación: AppKey (identificador único de la aplicación), AppSecret (usada para autenticación por firma; manténgala segura) y AppCode (usada para autenticación simple).

Consultar credenciales desde la consola de API Gateway: Inicie sesión en la consola de API Gateway, busque la aplicación objetivo en Application Management y vaya a la página de detalles de la aplicación para consultar la AppKey, AppSecret y AppCode.

AppSecret y AppCode son información sensible. No las exponga en repositorios de código, registros, páginas frontend u otras ubicaciones públicas. Si sospecha que las credenciales se han filtrado, restablezca inmediatamente la AppSecret en la consola de API Gateway.

Llamar a APIs mediante el SDK de API Gateway

API Gateway proporciona SDKs para los principales lenguajes de programación con implementaciones integradas del algoritmo de firma. Solo necesita proporcionar la AppKey y la AppSecret. Para obtener más información, consulte Call an API y SDK download and usage.

Lenguajes de SDK compatibles

Ventajas de usar el SDK

En comparación con la construcción manual de solicitudes HTTP, el SDK ofrece estas ventajas:

• Firma automática: El SDK implementa el algoritmo de firma HMAC-SHA256, por lo que los desarrolladores no necesitan manejar los detalles de la firma.

• Reintento automático: Algunos SDK incluyen mecanismos de reintento integrados para excepciones de red.

• Validación de parámetros: El SDK valida los parámetros antes de enviar las solicitudes.

• Optimización de rendimiento: Los SDK suelen usar agrupación de conexiones y HTTP/2 para mejorar el rendimiento de la red.

Ejemplo de integración rápida (Java)

El siguiente ejemplo muestra cómo llamar a una API de Data Service utilizando el SDK de Java de API Gateway:

// 1. Add Maven dependency // <dependency> // <groupId>com.aliyun.api.gateway</groupId> // <artifactId>sdk-core-java</artifactId> // <version>latest version</version> // </dependency> // 2. Initialize the client HttpClientBuilderParams params = new HttpClientBuilderParams(); params.setAppKey("your_app_key"); params.setAppSecret("your_app_secret"); ApacheHttpClient client = new ApacheHttpClient(params); // 3. Construct the request IoTApiRequest request = new IoTApiRequest(); request.setDomain("your-api-endpoint.cn-shanghai.alicloudapi.com"); request.setPath("/api/v1/query"); request.setHttpMethod("GET"); request.putQueryParam("pageSize", "10"); request.putQueryParam("pageNum", "1"); // 4. Execute the call ApiResponse response = client.execute(request); System.out.println("Response: " + response.getBody());

Ejemplo de integración rápida (Python)

1. Install the SDK # pip install aliyun-api-gateway-sdk # 2. Call the API from com.alibaba.cloudapi.sdk.client import DefaultClient from com.alibaba.cloudapi.sdk.model import HttpClientBuilderParams params = HttpClientBuilderParams() params.app_key = "your_app_key" params.app_secret = "your_app_secret" params.host = "your-api-endpoint.cn-shanghai.alicloudapi.com" client = DefaultClient(params) response = client.get( path="/api/v1/query", query_params={"pageSize": "10", "pageNum": "1"}, headers={"Accept": "application/json"} ) print(f"Status: {response.status_code}") print(f"Body: {response.content}")

Para instrucciones de uso detalladas, referencias de API y código de ejemplo para cada SDK de lenguaje, consulte la sección SDK download and usage en la documentación de API Gateway.

Resumen completo del proceso de llamada

El proceso completo desde la publicación de la API hasta una llamada exitosa es el siguiente: El desarrollador de API desarrolla, prueba y publica la API en API Gateway, que crea automáticamente una aplicación predeterminada y su autorización. Para compartir entre cuentas, el desarrollador autoriza manualmente la cuenta objetivo. El llamador de API crea una aplicación o usa la aplicación predeterminada, obtiene credenciales (AppKey/AppSecret/AppCode), elige un método de autenticación (AppCode para autenticación simple o AppKey + AppSecret para autenticación por firma) y llama a la API a través del SDK o HTTP. Después de que API Gateway verifica la identidad, Data Service ejecuta la consulta y devuelve los resultados.

Referencias

• Publish an API: Aprenda a publicar una API en API Gateway.

• Authorize an API: Obtenga información sobre las operaciones de autorización y la gestión de APIs autorizadas a otros.

• Test an API: Pruebe APIs publicadas o autorizadas en la página Service Management.