Estos contenidos se han traducido de forma automática para su comodidad, pero Huawei Cloud no garantiza la exactitud de estos. Para consultar los contenidos originales, acceda a la versión en inglés.

Centro de ayuda/ API Gateway/ Referencia de la API/ Las API de gateway compartido (para usuarios existentes)/ OpenAPI/ Importación de API a un grupo de API existente

Actualización más reciente 2025-12-22 GMT+08:00

Ver PDF

Importación de API a un grupo de API existente

Función

Esta API se utiliza para crear o actualizar API en un grupo de API mediante la importación de definiciones de Swagger. Se admiten archivos de Swagger en formato de JSON o YAML.

URI

La siguiente tabla muestra el método de solicitud HTTP/HTTPS y el URI de la API.

**Tabla 1**
Método de solicitud	URI
PUT	/v1.0/apigw/openapi?group_id={0}&mode={1}

En la siguiente tabla se enumeran los parámetros del URI.

**Tabla 2** Descripción de parámetro
Parámetro	Obligatorio	Tipo	Descripción
group_id	Sí	String	ID de grupo de API
mode	Sí	String	Medidas a tomar si se produce un conflicto. Opciones: merge y override. merge: conserva la API original. override: sobrescribe la API existente.
extend_mode	No	String	Modo de importación de definición extendida. Las opciones incluyen merge y override. Si la definición extendida entra en conflicto con la definición de API existente, puede elegir conservar o reemplazar la definición existente.

Solicitud

**Tabla 3** Descripción de parámetro
Parámetro	Obligatorio	Tipo	Descripción
swagger	Sí	String	El valor se fija en 2.0.
info	Sí	Object	Consulte Tabla 4.
paths	Sí	Object	Consulte Tabla 5.
responses	No	Object	Respuesta común, a la que se puede hacer referencia en el documento {method}. Para obtener más información, consulte Tabla 9.
securityDefinitions	Sí	Object	Definición del modo de autenticación de seguridad. Para obtener más información, consulte Tabla 13.
x-apigateway-access-controls	No	Object	Información de control de acceso. Para obtener más información, consulte Tabla 23.
x-apigateway-ratelimits	No	Object	Solicitud de información de limitación. Para obtener más información, consulte Tabla 25.

**Tabla 4** Descripción del parámetro de la información
Parámetro	Obligatorio	Tipo	Descripción
title	No	String	Nombre de un grupo de API. Este parámetro no tiene efecto cuando el grupo de API se importa a un grupo existente.
version	No	String	Número de versión. Puede especificar un número de versión o utilizar la fecha y hora actuales de forma predeterminada.
description	No	String	Descripción del grupo de API

**Tabla 5** Descripción de parámetros de paths
Parámetro	Obligatorio	Tipo	Descripción
uri	Sí	Object	Dirección de acceso de API. Para obtener más información, consulte Tabla 6.

**Tabla 6** Descripción del parámetro de uri
Parámetro	Obligatorio	Tipo	Descripción
method	Sí	Object	Método de acceso a la API. Para obtener más información, consulte Tabla 7.

**Tabla 7** Descripción de parámetros del método
Parámetro	Obligatorio	Tipo	Descripción
operationId	No	String	Nombre de la API
description	No	String	Descripción de la API
schemes	No	Object	Protocolo de solicitud de API. HTTP y HTTPS son compatibles.
tags	No	Object	Etiquetas de API
parameters	No	Object	Solicitud de definiciones de parámetros. Para obtener más información, consulte Tabla 8.
responses	No	Object	Definición de respuesta. Para obtener más información, consulte Tabla 9.
security	No	Object	Modo de autenticación de seguridad. Para obtener más información, consulte Tabla 10.
x-apigateway-access-control	No	Object	Política de control de acceso vinculada a la API
x-apigateway-backend	No	Object	Información de backend. Para obtener más información, consulte Tabla 15.
x-apigateway-backend-policies	No	Object	Información sobre la política de backend. Para obtener más información, consulte Tabla 16.
x-apigateway-cors	No	Boolean	Indica si se admite CORS.
x-apigateway-match-mode	No	String	Modo de coincidencia de ruta
x-apigateway-ratelimit	No	String	Nombre de la política de limitación de solicitudes vinculada a la API
x-apigateway-request-type	No	String	Tipo de API

**Tabla 8** Descripción del parámetro de frontend
Parámetro	Obligatorio	Tipo	Descripción
maximum	No	Float	Valor máximo de un parámetro de tipo de número
minimum	No	Float	Valor mínimo de un parámetro de tipo de número
maxLength	No	Integer	Longitud máxima de un parámetro de tipo de cadena
minLength	No	Integer	Longitud mínima de un parámetro de tipo de cadena
pattern	No	String	Expresión regular del valor del parámetro
type	No	String	Tipo
default	No	String	Valor predeterminado
description	No	String	Descripción de parámetro
name	No	String	Nombre del parámetro
in	No	String	Ubicación del parámetro, que puede ser path, header, query, formData o body
required	No	Boolean	Si se requiere el parámetro. El parámetro es necesario cuando su ubicación es path.

**Tabla 9** Descripción de parámetros de responses
Parámetro	Obligatorio	Tipo	Descripción
default	No	Object	Respuesta predeterminada, que se usará cuando no se defina ningún código de estado
status_code	No	Object	Código de estado de respuesta. El valor es un objeto de respuesta. Para obtener más información, consulte Tabla 11.
x-apigateway-result-failure-sample	No	String	Ejemplo de respuesta para una solicitud fallida
x-apigateway-result-normal-sample	No	String	Ejemplo de respuesta para una solicitud correcta

**Tabla 10** Descripción de parámetros de seguridad
Parámetro	Obligatorio	Tipo	Descripción
apig-auth-type	No	Object	Modo de autenticación de seguridad. Este parámetro es una matriz nula. Opciones: apig-auth-app: autenticación de aplicaciones apig-auth-iam: authenticación de IAM Null: No se requiere autenticación

**Tabla 11** Descripción del parámetro de status_code
Parámetro	Obligatorio	Tipo	Descripción
description	No	String	Descripción de la respuesta
schema	No	Object	Cuerpo de respuesta. Para obtener más información, consulte Tabla 12.

**Tabla 12** Descripción del parámetro del esquema
Parámetro	Obligatorio	Tipo	Descripción
description	No	String	Descripción del cuerpo
type	No	String	Tipo de cuerpo, que puede ser FORM o STREAM

**Tabla 13** Descripción de parámetros de securityDefinitions
Parámetro	Obligatorio	Tipo	Descripción
name	Sí	Object	Modo de autenticación de seguridad. Para obtener más información, consulte Tabla 14.

**Tabla 14** Parámetro descripción del nombre
Parámetro	Obligatorio	Tipo	Descripción
type	Sí	String	Tipo de autenticación. Se admite apiKey.
name	Sí	String	Nombre de apiKey
in	Sí	String	Ubicación de apiKey
x-apigateway-auth-type	Sí	String	Tipo de autenticación extendido basado en apiKey. Se admiten los tipos de autenticación de AppSigv1, IAM e IAM_NONE.

**Tabla 15** Descripción del parámetro de x-apigateway-backend
Parámetro	Obligatorio	Tipo	Descripción
type	Sí	String	Tipo de backend. Las opciones incluyen HTTP, HTTP-VPC, FUNCTION, y MOCK.
parameters	No	Object	Parámetros de backend. Para obtener más información, consulte Tabla 17.
backend_define	Sí	Object	Definición de backend Se admiten las siguientes definiciones de backend: httpEndpoints: consulte Tabla 18. httpVpcEndpoints: consulte Tabla 19. functionEndpoints: consulte Tabla 20. mockEndpoints: consulte Tabla 21.

**Tabla 16** Descripción del parámetro de x-apigateway-backend-policies
Parámetro	Obligatorio	Tipo	Descripción
type	Sí	String	Tipo de backend. Las opciones incluyen HTTP, HTTP-VPC, FUNCTION, y MOCK.
name	No	String	Nombre de política de backend
parameters	No	Object	Parámetros de backend. Para obtener más información, consulte Tabla 17.
backend_define	Sí	Object	Definición de backend Se admiten las siguientes definiciones de backend: httpEndpoints: consulte Tabla 18. httpVpcEndpoints: consulte Tabla 19. functionEndpoints: consulte Tabla 20. mockEndpoints: consulte Tabla 21.
conditions	Sí	Object	Condiciones de política. Para obtener más información, consulte Tabla 22.
effectMode	Sí	String	Modo efectivo de la política de backend. Las opciones incluyen ANY y ALL.

**Tabla 17** Descripción de parámetro de backend
Parámetro	Obligatorio	Tipo	Descripción
name	Sí	String	Nombre del parámetro, que consta de un máximo de 32 bytes, comenzando con una letra. Solo se permiten letras, dígitos, puntos (.), guiones (-) y guiones bajos (_). Los nombres de los parámetros de encabezado no distinguen entre mayúsculas y minúsculas.
value	Sí	String	Valor de parámetro, que es un nombre de parámetro si el parámetro proviene de una solicitud
in	Sí	String	Ubicación del parámetro, que puede ser header, query o path
origin	Sí	String	Fuente de asignación de parámetros. Las opciones incluyen REQUEST y CONSTANT.
description	No	String	Significado del parámetro

**Tabla 18** Descripción del parámetro del backend de httpEndpoints
Parámetro	Obligatorio	Tipo	Descripción
address	Sí	String	Dirección de servicio de backend. El formato es de <Domain name or IP address>:[Port number]
scheme	Sí	String	Protocolo de solicitud de backend. HTTP y HTTPS son compatibles.
method	Sí	String	Método de solicitud de backend. Las opciones incluyen GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH y ANY.
path	Sí	String	Ruta de solicitud de backend, que puede contener variables.
timeout	No	Integer	Tiempo de espera de la solicitud de backend en milisegundos. El valor oscila entre 1 y 60,000 y el valor predeterminado es 5000.
description	No	String	Descripción del backend

**Tabla 19** Descripción del parámetro de backend httpVpcEndpoints
Parámetro	Obligatorio	Tipo	Descripción
name	Sí	Array	Nombre del canal de VPC
scheme	Sí	String	Protocolo de solicitud de backend. HTTP y HTTPS son compatibles.
method	Sí	String	Método de solicitud de backend. Las opciones incluyen GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH y ANY.
path	Sí	String	Ruta de solicitud de backend, que puede contener variables.
timeout	No	Integer	Tiempo de espera de la solicitud de backend en milisegundos. El valor oscila entre 1 y 60,000 y el valor predeterminado es 5000.
host	No	String	host de proxy de canal de VPC
description	No	String	Descripción del backend

**Tabla 20** Descripción del parámetro de functionEndpoints de backend
Parámetro	Obligatorio	Tipo	Descripción
function-urn	Sí	String	Función URN
version	Sí	String	Versión de la función
invocation-type	Sí	String	Tipo de invocación de función. El valor puede ser async o sync.
timeout	No	Integer	Tiempo de espera de la función en milisegundos. El valor oscila entre 1 y 60,000 y el valor predeterminado es 5000.
description	No	String	Descripción del backend

**Tabla 21** Descripción del parámetro de mockEndpoints de backend
Parámetro	Obligatorio	Tipo	Descripción
result-content	Sí	String	Respuesta de simulacro
description	No	String	Descripción del backend

**Tabla 22** Descripción del parámetro de las condiciones
Parámetro	Obligatorio	Tipo	Descripción
type	Sí	String	Tipo de condición de política. Las opciones incluyen equal, enum y pattern.
value	Sí	String	Valor de condición de política
origin	Sí	String	Origen de la condición de la política. Las opciones incluyen source y request.
parameter	No	String	Nombre del parámetro de entrada si el parámetro origin está establecido en request.

**Tabla 23** Descripción del parámetro de x-apigateway-access-controls
Parámetro	Obligatorio	Tipo	Descripción
acl_name	No	Object	Política de control de acceso. Para obtener más información, consulte Tabla 24.

**Tabla 24** Descripción de parámetro de acl_name
Parámetro	Obligatorio	Tipo	Descripción
acl-type	Sí	String	Efecto de control de acceso. Las opciones incluyen PERMIT y DENY.
entity-type	Sí	String	Objeto de control de acceso. Solo se admiten direcciones IP y cuentas.
value	Sí	String	Valores de control de acceso, que se separan con comas (,).

**Tabla 25** Descripción del parámetro de x-apigateway-ratelimits
Parámetro	Obligatorio	Tipo	Descripción
throttle_name	No	Object	Solicitud de política de limitación. Para obtener más información, consulte Tabla 26.

**Tabla 26** Descripción del parámetro de throttle_name
Parámetro	Obligatorio	Tipo	Descripción
api-limit	Sí	Integer	Número máximo de veces que se puede invocar a una API
user-limit	No	Integer	Número de veces que un usuario puede invocar a la API
app-limit	No	Integer	Número de veces que una aplicación puede invocar a la API
ip-limit	No	Integer	Número de veces que se puede invocar a la API mediante una dirección IP
interval	Yes	Integer	Período de limitación
unit	Yes	String	Unidad de limitación, que puede ser SECOND, MINUTE, HOUR o DAY
shared	No	Boolean	Si desea compartir los límites de limitación entre las API
special	No	Object	Configuraciones de limitación de solicitudes excluidas. Para obtener más información, consulte Tabla 27.

**Tabla 27** Descripción del parámetro de special
Parámetro	Obligatorio	Tipo	Descripción
type	Sí	String	Tipo de estrangulamiento de solicitud excluido, que puede ser APP o USER
limit	Sí	Integer	Límite de acceso
instance	Sí	String	Aplicación o usuario excluido

Ejemplo de solicitud:

{
	"swagger": "2.0",
	"info": {
		"description": "api group test",
		"title": "APIGroup_test",
		"version": "2019-09-12-17:38:10"
	},

	"paths": {
		"/test/{path}": {
			"get": {
				"security": [
					{
						"apig-auth-app": []
					}
				],
				"description": "api test",
				"schemes": [
					"https"
				],
				"operationId": "API_test",
				"parameters": [
					{
						"type": "string",
						"description": "header parameter",
						"name": "header",
						"in": "header",
						"required": true
					},
					{
						"type": "string",
						"description": "path parameter",
						"name": "path",
						"in": "path",
						"required": true
					},
					{
						"type": "number",
						"default": "123",
						"description": "query parameter",
						"name": "query",
						"in": "query"
					}
				],
				"responses": {
					"default": {
						"$ref": "#/responses/default"
					},
					"x-apigateway-result-failure-sample": "",
					"x-apigateway-result-normal-sample": "success"
				},
				"x-apigateway-backend": {
					"httpEndpoints": {
						"address": "1.1.1.1:443",
						"description": "",
						"method": "GET",
						"path": "/test/{path}",
						"scheme": "https",
						"timeout": 5000
					},
					"parameters": [
						{
							"description": "",
							"in": "HEADER",
							"name": "header",
							"origin": "REQUEST",
							"value": "header"
						},
						{
							"description": "",
							"in": "PATH",
							"name": "path",
							"origin": "REQUEST",
							"value": "path"
						},
						{
							"description": "",
							"in": "QUERY",
							"name": "query",
							"origin": "REQUEST",
							"value": "query"
						}
					],
					"type": "HTTP"
				},
				"x-apigateway-backend-policies": [
					{
						"conditions": [
							{
								"origin": "param",
								"parameter": "path",
								"type": "exact",
								"value": "path"
							},
							{
								"origin": "source",
								"parameter": "",
								"type": "",
								"value": "1.0.0.0/8"
							}
						],
						"effectMode": "ANY",
						"httpVpcEndpoints": {
							"method": "POST",
							"name": "VPC_n9ct",
							"path": "/",
							"scheme": "HTTPS",
							"timeout": 5000
						},
						"name": "policy_test",
						"type": "HTTP-VPC"
					}
				],
				"x-apigateway-cors": false,
				"x-apigateway-match-mode": "NORMAL",
				"x-apigateway-request-type": "public"
			}
		}
	},
	"responses": {
		"default": {
			"description": "response example"
		}
	},
	"securityDefinitions": {
		"apig-auth-app": {
			"type": "apiKey",
			"name": "Authorization",
			"in": "header",
			"x-apigateway-auth-type": "AppSigv1"
		},
		"apig-auth-iam": {
			"type": "apiKey",
			"name": "unused",
			"in": "header",
			"x-apigateway-auth-type": "IAM"
		}
	}
}

Respuesta

**Tabla 28** Descripción de parámetro
Parámetro	Tipo	Descripción
group_id	String	ID de grupo de API
success	Array	Importar información de éxito
failure	Array	Importar información de error

**Tabla 29** Descripción del parámetro de success
Parámetro	Tipo	Descripción
id	String	ID de una API importada correctamente
action	String	Tipo de importación. Opciones: update: actualiza las API en un grupo de API existente. create: crea APIs para un nuevo grupo de API.
method	String	Método de solicitud
path	String	Ruta de solicitud

**Tabla 30** Descripción del parámetro de failure
Parámetro	Tipo	Descripción
error_code	String	Código de error
error_msg	String	Mensaje de error
method	String	Método de solicitud
path	String	Ruta de solicitud

Ejemplo de respuesta:

{
  "group_id": "27aa2317e3514c5bb5aab5587a5e50ea",
  "success": [
    {
      "id": "aea39194d8db46408be0174b0bd15931",
      "action": "create",
      "method": "GET",
      "path": "/test01"
    }
  ],
  "failure": [
    {
      "error_code": "APIG.2011",
      "error_msg": "Parameter value does not match the rules,parameterName:backend_type",
      "method": "GET",
      "path": "/test02"
    }
  ]
}

Códigos de estado

**Tabla 31** Códigos de estado
Código de estado	Descripción
200	OK
400	Bad Request
403	Forbidden
500	Server Internal Error

Tema principal: OpenAPI

Tema anterior: Importación de API a un nuevo grupo de API

Tema siguiente: Gestión de autorizador personalizado

Comentarios

¿Le pareció útil esta página?

Sí No

Deje algún comentario

Muchas gracias por sus comentarios. Seguiremos trabajando para mejorar la documentación.

El sistema está ocupado. Vuelva a intentarlo más tarde.