:ImportImage

Observações de uso

Atente-se aos seguintes pontos:

• Antes de importar uma imagem, carregue-a em um bucket do Object Storage Service (OSS). Para mais informações, consulte Upload objects.

• Em alguns cenários, talvez seja necessário criar uma imagem com base nos dados do sistema operacional de um servidor de origem, importá-la para o ECS e, em seguida, criar uma instância ECS a partir dessa imagem. O servidor de origem pode ser físico, virtual ou um host em nuvem. Se o driver virtio não estiver instalado no servidor de origem, a instância ECS criada poderá falhar ao iniciar. Para evitar esse problema, verifique se o driver virtio está instalado no servidor de origem antes de importar a imagem. Para mais detalhes, consulte Install the virtio driver.

• Antes de importar imagens pela primeira vez, autorize o ECS a acessar seus buckets do OSS por meio do Resource Access Management (RAM). Sem essa autorização, a operação ImportImage retornará o código de erro NoSetRoletoECSServiceAcount. Conclua a autorização com um único clique na página Cloud Resource Access Authorization no console RAM. Também é possível concluir a autorização usando uma função RAM e políticas RAM. Os exemplos abaixo mostram as políticas e permissões necessárias para algumas etapas do procedimento. Para mais informações, consulte Control access to resources by using RAM users.

  1. Crie uma função chamada AliyunECSImageImportDefaultRole. É obrigatório usar exatamente esse nome; caso contrário, a importação da imagem falhará. Configure a seguinte política de confiança para a função: { "Statement": [ { "Action": "sts:AssumeRole", "Effect": "Allow", "Principal": { "Service": [ "ecs.aliyuncs.com" ] } } ], "Version": "1" }

  2. Anexe a política de sistema AliyunECSImageImportRolePolicy à função. Alternativamente, crie uma política personalizada com o conteúdo abaixo e anexe-a à função: { "Version": "1", "Statement": [ { "Action": [ "oss:GetObject", "oss:GetBucketLocation", "oss:GetBucketInfo" ], "Resource": "*", "Effect": "Allow" } ] }

• Não é possível excluir uma imagem durante a importação. No entanto, chame a operação CancelTask para cancelar a tarefa de importação.

• Importe a imagem apenas para a mesma região do bucket OSS onde o arquivo de imagem foi carregado.

• Os valores válidos de N em DiskDeviceMapping.N variam de 1 a 17. Quando N é igual a 1, o disco é considerado disco do sistema. Para valores entre 2 e 17, trata-se de disco de dados. Se N for maior que 17, os parâmetros com o prefixo DiskDeviceMapping.N serão ignorados.

• Ao definir Architecture como arm64 ou Platform como CentOS Stream, Anolis, AlmaLinux, UOS, Kylin ou Rocky Linux, observe os requisitos abaixo:

  • Para garantir a definição de senha ou a modificação do par de chaves na imagem importada, certifique-se de que ela atenda aos seguintes critérios antes da importação:

    • O kernel do sistema operacional deve suportar o recurso CONFIG_FW_CFG_SYSFS. Por padrão, kernels Linux community 4.6+ e CentOS 3.10.0-826.el7+ já incluem esse suporte. Execute o comando grep -nr CONFIG_FW_CFG_SYSFS /boot/config-$(uname -r) no servidor de origem da imagem. Se a saída contiver CONFIG_FW_CFG_SYSFS=y, o kernel possui o suporte necessário.

    • A versão mais recente do cloud-init da Alibaba Cloud deve estar instalada no sistema operacional. Para a versão 19.1, a subversão mínima exigida é 19.1.3. Em sistemas mais antigos que utilizam a versão 0.7.6a, a subversão deve ser pelo menos 0.7.6a15. Consulte Install cloud-init para mais detalhes.

    • O sistema operacional precisa oferecer suporte ao algoritmo de criptografia SHA-512.

  • Para permitir o redimensionamento de discos e sistemas de arquivos na imagem importada, verifique se os pré-requisitos abaixo são atendidos antes da importação:

    • A versão do kernel do sistema operacional deve ser superior a 3,6.

    • A imagem deve suportar o comando growpart, o que requer a instalação do pacote cloud-utils-growpart. O método de instalação varia conforme o sistema operacional. Consulte Extend the partitions and file systems of disks on a Linux instance para instruções específicas.

    • É necessário suporte ao comando resize2fs, que depende do pacote e2fsprogs. Esse pacote geralmente vem pré-instalado; caso contrário, instale-o.

    • Instale a versão mais recente do cloud-init da Alibaba Cloud. Se estiver usando a versão 19.1, a subversão mínima é 19.1.3. Para versões antigas baseadas em 0.7.6a, utilize pelo menos a subversão 0.7.6a15. Mais informações em Install cloud-init.

• Se a imagem a ser importada utilizar a arquitetura ARM64, configure o relógio de tempo real (RTC) para o padrão UTC (Tempo Universal Coordenado). Consulte Linux time and time zones para orientações.

• Recomendamos especificar o parâmetro DetectionStrategy durante a importação. Isso permite otimizar a imagem com base nos resultados da verificação. Para detalhes, consulte Image check items.

Depuração

O OpenAPI Explorer calcula automaticamente o valor da assinatura. Para sua conveniência, recomendamos chamar esta operação diretamente no OpenAPI Explorer, que também gera dinamicamente códigos de exemplo para diferentes SDKs.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Exemplo	Descrição
Action	String	Sim	ImportImage	A operação a ser executada. Defina o valor como ImportImage.
RegionId	String	Sim	cn-hangzhou	ID da região do bucket OSS onde a imagem a ser importada foi carregada. Chame a operação DescribeRegions para obter a lista atualizada de regiões.
ImageName	String	Não	ImageTestName	Nome da imagem. Deve ter entre 2 e 128 caracteres, iniciando com uma letra. Não pode começar com acs: ou aliyun, nem conter http:// ou https://. São permitidos letras, dígitos, pontos (.), dois-pontos (:), sublinhados (_) e hifens (-).
Description	String	Não	TestDescription	Descrição da imagem. Deve possuir entre 2 e 256 caracteres e não pode iniciar com http:// ou https://.
Architecture	String	Não	x86_64	Arquitetura do sistema operacional. Valores válidos: i386 x86_64 arm64 Valor padrão: x86_64.
OSType	String	Não	linux	Plataforma do sistema operacional. Valores válidos: windows linux Valor padrão: linux.
Platform	String	Não	Aliyun	Distribuição do sistema operacional. Valores válidos: Aliyun Anolis CentOS Ubuntu CoreOS SUSE Debian OpenSUSE FreeBSD RedHat Kylin UOS Fedora Fedora CoreOS CentOS Stream AlmaLinux Rocky Linux Gentoo Customized Linux Others Linux Windows Server 2022 Windows Server 2019 Windows Server 2016 Windows Server 2012 Windows Server 2008 Windows Server 2003 Valor padrão: Others Linux.
BootMode	String	Não	BIOS	Modo de inicialização da imagem. Valores válidos: BIOS UEFI Valor padrão: BIOS. Caso defina o parâmetro Architecture como arm64, configure este parâmetro como UEFI. Nota É essencial conhecer os modos de inicialização suportados pela imagem especificada. Ao alterar o modo de inicialização através deste parâmetro, selecione um modo compatível com a imagem para garantir que as instâncias iniciem corretamente.
RoleName	String	Não	AliyunECSImageImportDefaultRole	Nome da função RAM utilizada para importar a imagem.
LicenseType	String	Não	Auto	Tipo de licença para ativação do sistema operacional após a importação. Valores válidos: Auto: O ECS detecta o sistema operacional da imagem e atribui uma licença adequada. Primeiramente, verifica-se se existe licença oficial da Alibaba Cloud para a distribuição indicada em Platform. Em caso positivo, essa licença é aplicada; caso contrário, utiliza-se a licença original do sistema operacional de origem. Aliyun: Utiliza a licença fornecida por canal oficial da Alibaba Cloud para a distribuição definida em Platform. BYOL: Mantém a licença do sistema operacional de origem. Certifique-se de que sua chave de licença é válida para uso na Alibaba Cloud. Valor padrão: Auto.
ResourceGroupId	String	Não	rg-bp67acfmxazb4p****	ID do grupo de recursos ao qual a imagem será atribuída.
DiskDeviceMapping.N.DiskImSize	Integer	Não	80	Tamanho do disco N na imagem personalizada após a importação. Unidade: GiB. Este parâmetro define as dimensões do disco do sistema e dos discos de dados na imagem personalizada. Ao especificar o tamanho do disco do sistema, o valor deve ser igual ou superior ao tamanho do arquivo de imagem importado. Unidade: GiB. Valores válidos: Quando N for 1, define o tamanho do disco do sistema. Intervalo válido: 5 a 500. Quando N for um inteiro entre 2 e 17, define o tamanho de um disco de dados. Intervalo válido: 5 a 2000. Após carregar o arquivo de imagem em um bucket OSS, consulte o tamanho do arquivo diretamente no bucket. Nota Este parâmetro será descontinuado futuramente. Recomendamos o uso de DiskDeviceMapping.N.DiskImageSize para garantir compatibilidade futura.
DiskDeviceMapping.N.Device	String	Não	null	Nome do dispositivo do disco N na imagem personalizada. Nota Este parâmetro será removido em versões futuras. Evite utilizá-lo para assegurar compatibilidade.
DiskDeviceMapping.N.OSSBucket	String	Não	ecsimageos	Bucket OSS onde a imagem está armazenada. Nota Antes da primeira importação, autorize o ECS a acessar seus buckets OSS via RAM. Sem essa permissão, a operação ImportImage retornará o erro NoSetRoletoECSServiceAcount. Consulte a seção "Observações de uso" neste tópico para mais detalhes.
DiskDeviceMapping.N.Format	String	Não	QCOW2	Formato da imagem. Valores válidos: RAW VHD QCOW2 Por padrão, este campo fica vazio, indicando que o sistema detectará automaticamente o formato da imagem e preencherá o valor.
DiskDeviceMapping.N.OSSObject	String	Não	CentOS_5.4_32.raw	Nome (chave) do objeto correspondente à imagem carregada no bucket OSS.
DiskDeviceMapping.N.DiskImageSize	Integer	Não	80	Tamanho do disco N na imagem personalizada após a importação. Utilize este parâmetro para definir as capacidades do disco do sistema e dos discos de dados. Para o disco do sistema, o tamanho especificado deve ser maior ou igual ao do arquivo de imagem importado. Unidade: GiB. Valores válidos: Se N for 1, refere-se ao disco do sistema. Faixa aceita: 5 a 500. Se N estiver entre 2 e 17, refere-se a um disco de dados. Faixa aceita: 5 a 2000. Verifique o tamanho do arquivo de imagem no bucket OSS após concluir o upload.
Tag.N.Key	String	Não	TestKey	Chave da tag N a ser adicionada à imagem personalizada. N varia de 1 a 20. A chave não pode ser vazia, deve ter até 128 caracteres e não pode conter http:// ou https://. Também não pode iniciar com acs: ou aliyun.
Tag.N.Value	String	Não	TestValue	Valor da tag N a ser adicionada à imagem personalizada. N varia de 1 a 20. O valor pode ser uma string vazia, ter até 128 caracteres e não pode conter http:// ou https://. Não deve iniciar com acs:.
DetectionStrategy	String	Não	Standard	Modo de verificação da imagem. Se omitido, nenhuma verificação será realizada. Apenas o modo padrão é suportado. Nota Compatível com a maioria das imagens Linux e Windows. Para detalhes sobre itens verificados e limitações por sistema operacional, consulte Overview of image check e Operating system limits for image check.

Parâmetros de resposta

Parâmetro	Tipo	Exemplo	Descrição
RequestId	String	473469C7-AA6F-4DC5-B3DB-A3DC0DE3****	ID da requisição.
ImageId	String	m-bp67acfmxazb4p****	ID da imagem.
TaskId	String	t-bp67acfmxazb4p****	ID da tarefa de importação da imagem.
RegionId	String	cn-hangzhou	ID da região da imagem.

Exemplos

Exemplos de requisições

http(s)://ecs.aliyuncs.com/?Action=ImportImage
&RegionId=cn-hangzhou
&DiskDeviceMapping.1.Format=QCOW2
&DiskDeviceMapping.1.OSSBucket=ecsimageos
&DiskDeviceMapping.1.OSSObject=CentOS_5.4_32.raw
&DiskDeviceMapping.1.DiskImageSize=80
&ImageName=Test
&Description=Test
&Architecture=x86_64
&OSType=linux
&Platform=Aliyun
&LicenseType=Aliyun
&DetectionStrategy=Standard
&<Common request parameters>

Exemplos de respostas de sucesso

Formato XML

HTTP/1.1 200 OK
Content-Type:application/xml

<ImportImageResponse>
    <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3****</RequestId>
    <ImageId>m-bp67acfmxazb4p****</ImageId>
    <TaskId>t-bp67acfmxazb4p****</TaskId>
    <RegionId>cn-hangzhou</RegionId>
</ImportImageResponse>

Formato JSON

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "473469C7-AA6F-4DC5-B3DB-A3DC0DE3****",
  "ImageId" : "m-bp67acfmxazb4p****",
  "TaskId" : "t-bp67acfmxazb4p****",
  "RegionId" : "cn-hangzhou"
}

Códigos de erro

Código de status HTTP	Código de erro	Mensagem de erro	Descrição
400	UnsupportedSuffix.OSSObject	The specified OSS object suffix is not supported.	O sufixo do objeto OSS especificado não é suportado.
400	InvalidImageName.Malformed	The specified Image name is wrongly formed.	Formato inválido para ImageName. O nome deve ter entre 2 e 128 caracteres, iniciar com letra e não pode começar com acs: ou aliyun. Não pode conter http:// ou https://. Permite letras, números, pontos (.), dois-pontos (:), sublinhados (_) e hifens (-).
400	InvalidOSSObject.Malformed	The specified OSS object is wrongly formed.	Valor inválido para DiskDeviceMapping.N.OSSObject.
400	InvalidDescription.Malformed	The specified Image description is wrongly formed.	Formato inválido para Description.
400	InvalidArchitecture.Malformed	The specified Architecture is wrongly formed.	Formato inválido para Architecture.
400	InvalidPlatform.Malformed	The specified Platform is wrongly formed.	Valor inválido para Platform.
400	InvalidOSType.Malformed	The specified OSType is wrongly formed.	Formato inválido para OSType.
400	InvalidImageName.Duplicated	The destination image is exist.	O nome da imagem já existe.
400	InvalidImageSize	%s	Tamanho de imagem inválido.
400	InvalidDataDiskSize	The specified DiskDeviceMapping.N.DiskImSize should be in the specified range.	Valor inválido para DiskDeviceMapping.N.DiskImSize.
400	InvalidImageFormat.Malformed	The specified Image Format is wrongly formed.	Valor inválido para ImageFormat.
400	InvalidRegionId.NotFound	The specified RegionId does not exist.	Valor inválido para RegionId.
400	InvalidRegion.NotSupport	The specified region does not support image import or export.	Esta operação não pode ser executada na região especificada.
400	InvalidOSSBucket.NotFound	The specified OSS bucket does not exist in this region.	Bucket OSS não encontrado.
400	InvalidOSSObject.NotFound	The specified OSS object does not exist in this region.	Objeto OSS não encontrado.
400	InvalidOSSBucket.NotMatched	The specified OSS bucket is incorrect, %s.	Valor inválido para DiskDeviceMapping.N.OSSBucket. Consulte o valor retornado no placeholder %s da mensagem de erro.
403	ImageIsImporting	The specified Image is importing.	A imagem especificada está sendo importada. A operação não pode ser realizada.
403	QuotaExceed.Image	The Image Quota exceeds.	A cota de imagens personalizadas foi atingida.
403	ImportImageFailed	Importing image is failed, Please contact the administrator.	Falha na importação da imagem. Entre em contato com o administrador do sistema.
403	UserNotInTheWhiteList	The user is not in the white list of importing image.	Você não tem autorização para importar imagens.
403	NoSetRoletoECSServiceAcount	ECS service account Have no right to access your OSS.please attach a role of access your oss to ECS service account.	O ECS não possui autorização para acessar o bucket ou objeto OSS especificado.
403	MissingParameter.DiskDeviceMapping	The specified parameter DiskDeviceMapping is not supplied.	É necessário fornecer um parâmetro iniciado com DiskDeviceMapping.
403	InvalidVHDImage.IncorrectSize	The specified size of the VHD image does not meet the 'header.MaxTableEntries * header.BlockSize' specification.	O tamanho da imagem VHD não respeita o limite definido por header.MaxTableEntries multiplicado por header.BlockSize.
403	InvalidOSSBucket.EncryptUnsupported	Accessing objects from encrypted OSS bucket is not supported.	Não é possível ler objetos de buckets OSS criptografados.
403	InvalidArchitecture.PlatformUnsupported	The OS platform you selected does not support the specified architecture.	O sistema operacional selecionado não suporta a arquitetura especificada.
403	InvalidAccountStatus.OSSDisabled	OSS is disabled due to invalid account status.	O OSS está desativado devido a status inválido da conta.
404	InvalidResourceGroup.NotFound	The ResourceGroup provided does not exist in our records.	Grupo de recursos não encontrado.

Para consultar a lista completa de códigos de erro, acesse Service error codes.