image, volume, vpc o iam_role. Cuando se admite, el mismo campo acepta un UUID, un nombre de recurso de la nube (CRN) o un nombre. La descripción de la API de cada campo define sus tipos y alcance aceptados; un recurso que tiene un nombre no significa que todas las operaciones puedan resolver ese nombre.
Cómo se clasifica una referencia
La clasificación utiliza la sintaxis de entrada, antes de buscar un recurso:- Un prefijo literal, sensible a mayúsculas y minúsculas
crn:selecciona el análisis CRN. Un CRN mal formado es un error; nunca se vuelve a intentar como nombre. - Un UUID de 36 caracteres en forma hexadecimal
8-4-4-4-12selecciona la búsqueda de UUID. Las letras hexadecimales pueden ser mayúsculas o minúsculas. - Todo lo demás selecciona la validación de nombres y la búsqueda para ese tipo de recurso.
crn: o usar una ortografía UUID, incluyendo ortografías compactas, entre corchetes y URN UUID. Cada servicio también aplica su propia sintaxis de nombres. Estas formas reservadas mantienen los nombres separados de los identificadores.
Identidades canónicas
Una referencia elige un recurso existente. Las respuestas devuelven su identidad canónica, no la ortografía que envió. Los enlaces de relación conservan el UUID resuelto; reutilizar el nombre de un recurso eliminado no redirige un enlace existente. Un CRN tiene esta forma:platform.
Para cada recurso con un nombre único elegido por el usuario, ese nombre es su identidad CRN. Los nombres y por lo tanto los CRN son inmutables. Una etiqueta de visualización mutable es una propiedad independiente: los nombres de usuario y organización de IAM, los nombres de visualización de cuentas y las etiquetas de clave de seguridad no se convierten en identidades de referencia basadas en nombres. La identidad de la cuenta utiliza su identificador inmutable.
Los recursos sin un nombre único elegido por el usuario usan identidades UUID donde exponen CRN de recursos. Entre los ejemplos se incluyen IP flotantes, registros DNS, copias de seguridad de bases de datos, escuchas y reglas de equilibrador de carga, usuarios y organizaciones de IAM, credenciales, eventos de auditoría y registros de facturación. El nombre de propietario de un registro DNS es un dato de protocolo y puede aparecer en varios registros. Una etiqueta de copia de seguridad o una dirección IP flotante no es una referencia de nombre de recurso. Las versiones secretas numeradas y los tokens de catálogo/protocolo siguen el contrato explícito de su punto final.
CRNs de alcance parental
Un hijo anexa un par tipo/identidad al CRN completo de su padre. El CRN padre es un prefijo literal, preservando cada ancestro:inline-policy/<name> a su CRN principal.
Las cargas útiles de protocolo tienen excepciones explícitas a los pares estructurales: las claves de objeto de bucket siguen siendo claves opacas que contienen barras oblicuas después del nombre del bucket, y los nombres de log-group pueden contener barras oblicuas. Las expresiones de comodín de directiva son patrones de directiva, no referencias de solicitud concretas.
Rutas de recursos
Usa el UUID devuelto en una ruta de recurso declarada como un UUID, comoGET /v1/instances/{instance_id}. No ponga un nombre o CRN con barras en esa ruta. Las rutas de protocolo, incluidos los nombres de depósito y los nombres de usuario/base de datos de la base de datos, conservan los tipos de parámetros mostrados por sus operaciones.
Ámbitos de resolución
Las solicitudes de red de cómputo y base de datos no proporcionan la VPC necesaria para una búsqueda de subred desnuda. Utilice un UUID de subred o un CRN anidado completo. La creación de un balanceador de carga proporciona una VPC y puede resolver un nombre de subred en ella. Una actualización de subred puede derivar su VPC de la subred de propiedad. Una referencia nunca evita las comprobaciones de propiedad, pertenencia a la familia principal, disponibilidad, confianza o permisos.
Los CRN de certificados usan una ranura de región vacía aunque las solicitudes de certificados usan un extremo regional. Copia los CRN de respuesta canónica en lugar de inferir su ámbito a partir de un nombre de host.
Nombres y versiones de imágenes
Los campos de referencia de imagen admiten estos formularios:
Las búsquedas de nombre y
name:version usan la arquitectura de la solicitud, por defecto amd64 cuando se omite. Un CRN proporciona su propia arquitectura y versión; un UUID ya identifica una compilación. Los nombres consideran las imágenes de tu cuenta y plataforma pública. Entre las coincidencias utilizables, su cuenta gana sobre la plataforma. Un CRN explícito selecciona solo al propietario declarado. Las imágenes de otro cliente e imágenes de plataforma privada no están disponibles para usted, incluso si conoce sus UUID.
Un nombre actual puede seleccionar una versión más reciente en una solicitud posterior. Un UUID, etiqueta de versión o CRN completo fija una compilación; las plantillas de grupo de instancias almacenan el UUID de imagen resuelto. La retirada no redirige una referencia fija a un reemplazo. Una imagen retirada devuelve IMAGE_NOT_FOUND; cuando la información de fin de vida está disponible, su mensaje explica la retirada. Las coincidencias visibles utilizables tienen prioridad sobre los diagnósticos de retirada. Tratar el código de error como estable y el mensaje como texto para una persona.
Errores y límites de protocolo
Para la resolución de relaciones, la sintaxis malformada, un tipo de referencia no compatible, un servicio/tipo incorrecto o un ancestro incompleto produce un error de validación. El resolutor compartido también rechaza una región incorrecta como entrada no válida. Un objetivo o cuenta extranjera que falta se informa como no encontrado. Los servicios conservan sus códigos documentados específicos de recursos y errores de permisos; inspeccione las respuestas de error de la operación. No intente otra referencia después de un error. Un filtro de colección exacta es un selector, no una búsqueda de relación. Un CRN extranjero válido o no coincidente no selecciona filas. Los CRN malformados o vacíos devuelven 400; los detalles de validación específicos del punto final se enumeran a continuación. Un resultado vacío no es un intento fallido de resolver un nombre. Los parámetros de región usan códigos de región comosa-saopaulo-1, no UUIDs, CRNs o nombres de visualización. Los selectores de resource y actor de auditoría buscan instantáneas históricas de UUID/CRN sin requerir que el objetivo siga existiendo; los nombres nudos no son referencias históricas. El crn de la colección de auditoría selecciona el evento en sí.
Las claves de objeto, los tokens de carga/versión, el contenido de registro DNS, los identificadores de cliente OAuth, los identificadores de traza/rango, los nombres de métrica, las etiquetas de flujo de registro y los destinos IP literales conservan su significado de protocolo. Los campos de referencia de KMS y de grupo de registro siguen siguiendo sus contratos de recursos declarados. En particular, el marcador de posición AES256 del cifrado de depósito de S3 no implica compatibilidad con un destino KMS.
Listas exactas
Cuando se declaran,name y crn son predicados exactos combinados con AND, con propiedad, padre y otros filtros aplicados antes de la paginación. name=web-* no significa una búsqueda por prefijo. Un filtro omitido difiere de uno explícitamente vacío: name= retiene un predicado vacío, y crn= sigue la validación específica del punto final a continuación. Nunca elimine un filtro vacío y vuelva a intentarlo, porque eso ampliaría la solicitud.
Las listas de nombres de subred de nivel superior y de tabla de rutas requieren vpc; las listas de nombres de interfaz requieren subnet (y vpc cuando esa subred es un nombre desnudo). Las listas de nombres de instantáneas requieren volume. Un CRN hijo completo proporciona su propio origen, pero cualquier filtro padre adicional debe estar de acuerdo. Las listas de NIC de instancia en su lugar coinciden con los nombres de interfaz dentro de los enlaces de esa instancia, por lo que los nombres duplicados de diferentes subredes pueden producir múltiples coincidencias.
Un selector de nombre declarado no necesita identificar un recurso único. Las listas de nombres para mostrar de IAM, los nombres de propietarios de registros DNS y los nombres de imágenes en diferentes arquitecturas/versiones pueden coincidir con varias filas. Los nombres de zona DNS se escriben en minúsculas para la coincidencia. Las listas de recursos sin nombre que declaran name no devuelven coincidencias para él: esto incluye IP flotantes, rutas, reglas de grupo de seguridad, copias de seguridad de bases de datos y recursos secundarios de balanceador de carga. Los catálogos de motores de base de datos/parámetros no tienen CRN de recursos y no coinciden con ningún selector de CRN; los nombres de los tipos de volumen de almacenamiento son etiquetas de visualización exactas (SSD, NVMe), con CRN de catálogo basados en tokens. Las versiones secretas exponen CRNs secundarios numerados y no hay filtro de nombres. include_deleted puede hacer que un nombre secreto coincida con múltiples identidades.
Detalles de validación de lista
La sintaxis malformada y los selectores CRN vacíos devuelven 400 en las colecciones de recursos siguientes, incluidos los grupos de registro, IAM, KMS y secretos. Las identidades extranjeras válidas y los predicados de nombre/CRN no coincidentes devuelven una colección vacía, no un error de relación no encontrada. La estricta validación de ascendencia en computación, red, almacenamiento, base de datos, IAM, KMS y secretos también rechaza las cadenas secundarias incompletas. Las listas de registros y certificados DNS analizan primero la sintaxis y tratan un tipo o ascendencia estructuralmente analizable pero incompatible como una coincidencia vacía. Las listas de certificados rechazan un segmento de nombre de certificado no válido. Las listas de versiones secretas rechazan números de versión no válidos, incluyendo números cero y no canónicos como01.
La autorización de ruta principal sigue aplicándose a las listas anidadas. Los selectores exactos no convierten un padre inaccesible en una colección vacía exitosa.
Operaciones de cobro
Cada enlace a continuación da los parámetros exactos de la operación, la forma de respuesta y el contrato de paginación. “Protocolo” significa usar los selectores documentados de esa operación; no tiene un par genérico de recursosname/crn.
Obtener un recurso por cualquier referencia
Clasifica la entrada usando las reglas anteriores. Para un UUID, llama directamente a la operación GET del UUID del recurso. Para un nombre o CRN, consulte su colección con el filtro exacto correspondiente y el ámbito principal requerido. Siga la paginación hasta que pueda establecer si coincide exactamente un recurso. Cero coincidencias significa que no hay coincidencia visible; las coincidencias múltiples requieren un ámbito más específico o un CRN canónico. Nunca elija la primera fila arbitrariamente. Usa elid devuelto para llamadas subsiguientes a la ruta UUID. Si ese GET no devuelve nada, el recurso puede haber sido eliminado entre llamadas.
Estos son los destinos de solicitud HTTP; firmar cada solicitud usando tu autenticación normal y contexto de cuenta. Los valores de consulta deben estar codificados en URL.
web-01:
/v1/subnets?vpc=production&name=private; para un nombre de instantánea, utilice /v1/snapshots?volume=data&name=daily.
Las etiquetas de relación de imagen no son nombres literales de lista de imágenes: consulte name y architecture con all_versions=true, luego haga coincidir la versión devuelta y aplique la precedencia de llamada/plataforma documentada. No hay parámetro de consulta version público. Un CRN de imagen completa selecciona la identidad fijada; use all_versions=true cuando busque a través de las compilaciones reemplazadas. Las colecciones de protocolo y los recursos sin un UUID GET usan el propio contrato de recuperación de su operación.
CLI liberada
CLI v0.13.0 acepta una referencia paraget en recursos con una lista y una operación de obtención. Configure su perfil y la cuenta seleccionada como se describe en CLI; reemplace las identidades de ejemplo con sus recursos.
--vpc se rechaza con 400, name requires the resource's parent filter. Un CRN hijo completo proporciona su ascendencia. Los IDs padres que son argumentos posicionales siguen siendo IDs; use la opción --help del comando para sus indicadores de ámbito.
El getter de referencia no cambia otros verbos: delete, start y otros comandos de toma de ID aún necesitan el ID devuelto. Los indicadores de relación como instance create --image tienen sus propios contratos de referencia documentados.
Lanzamiento de Go SDK
Utilicegithub.com/basaltic-sh/sdk-go v0.15.0. Configure las credenciales, la cuenta y la región a través de BASALTIC_ACCESS_KEY_ID, BASALTIC_SECRET_ACCESS_KEY, BASALTIC_ACCOUNT_ID y BASALTIC_REGION. Este ejemplo lee la misma instancia por sus tres formas de referencia y lee una subred con su ámbito de VPC:
GetInstanceByReference y GetSubnetByReference llaman al getter UUID para un UUID y al filtro de colección exacto para un nombre o CRN. No coincidencia es un error no encontrado; múltiples coincidencias producen AmbiguousReferenceError. Ninguno de los dos reintenta un tipo de referencia diferente. El argumento final de ámbito puede ser nil cuando no se necesita ningún filtro padre o adicional. Utilice el ID devuelto con métodos SDK ordinarios como GetInstance y StartInstance.
Los clientes lanzados no tienen comandos de base de datos ni paquete de SDK de base de datos. Utilice los ejemplos HTTP de la página de la base de datos para esas operaciones. Las etiquetas de relación de imagen name:version no son nombres genéricos de getter; use el procedimiento de lista de imágenes anterior para seleccionar una compilación.