Como usar a biblioteca de cliente Python

Neste documento, você aprenderá a usar a biblioteca de cliente Python do Google para o Compute Engine. Veja como autorizar solicitações e como criar, listar e excluir instâncias. Neste exercício, é discutido como usar a biblioteca google-api-python-client para acessar os recursos do Google Compute Engine. Execute este exemplo pela máquina local ou em uma instância de VM, desde que você tenha autorizado a amostra corretamente.

Para ver uma lista completa das bibliotecas de cliente disponíveis, inclusive outras bibliotecas do Google e de código aberto de terceiros, consulte a página Bibliotecas de cliente.

Para pular o exercício e ver o código de exemplo completo, visite a página do GitHub GoogleCloudPlatform/python-docs-samples.

Objetivos

  • Definir autorizações do OAuth 2.0 usando a biblioteca oauth2client.
  • Criar uma instância usando a biblioteca google-python-client.
  • Listar instâncias usando a biblioteca google-python-client.
  • Excluir uma instância usando a biblioteca google-python-client.

Custos

Neste tutorial, há componentes do Cloud Platform passíveis de cobrança, incluindo o Google Compute Engine.

Novos usuários do Cloud Platform podem se qualificar para uma avaliação gratuita.

Antes de começar

  1. Faça login na sua Conta do Google.

    Se você ainda não tiver uma, inscreva-se.

  2. Selecione ou crie um projeto do Google Cloud Platform.

    Acessar a página Gerenciar recursos

  3. Verifique se o faturamento foi ativado no projeto do Google Cloud Platform.

    Saiba como ativar o faturamento

  4. Instale o SDK do Cloud.
  5. Uma vez instalado, execute gcloud auth application-default login .
  6. Instale a biblioteca google-api-python-client. Normalmente, é possível executar:
    $ pip install --upgrade google-api-python-client

    Para mais informações sobre como instalar essa biblioteca, consulte as instruções de instalação. Também é necessário ter o Python 2.7 ou 3.3+ para executar a biblioteca de cliente Python do Google.

  7. Ative a API Google Cloud Storage.
  8. Crie um intervalo de armazenamento e anote o nome do intervalo para uso posterior.

Autorizar solicitações

Este exemplo usa autorização do OAuth 2.0. Há várias maneiras de autorizar solicitações usando o OAuth 2.0, mas, neste exemplo, você usará o Application Default Credentials. Isso permite que você reutilize as credenciais da ferramenta gcloud se estiver executando a amostra em uma estação de trabalho local ou se reutilizar credenciais de uma conta de serviço, caso esteja executando a amostra no Compute Engine ou no App Engine. É necessário instalar e autorizar a ferramenta gcloud, conforme as instruções na seção Antes de começar.

As credenciais padrão do aplicativo são fornecidas nas bibliotecas de cliente da API Google automaticamente. Você só precisa compilar e inicializar a API:

compute = googleapiclient.discovery.build('compute', 'v1')

Por exemplo, o seguinte snippet é o método principal desta amostra, que compila e inicializa a API e faz algumas chamadas para criar, listar e excluir uma instância:

def main(project, bucket, zone, instance_name, wait=True):
    compute = googleapiclient.discovery.build('compute', 'v1')

    print('Creating instance.')

    operation = create_instance(compute, project, zone, instance_name, bucket)
    wait_for_operation(compute, project, zone, operation['name'])

    instances = list_instances(compute, project, zone)

    print('Instances in project %s and zone %s:' % (project, zone))
    for instance in instances:
        print(' - ' + instance['name'])

    print("""
Instance created.
It will take a minute or two for the instance to complete work.
Check this URL: http://storage.googleapis.com/{}/output.png
Once the image is uploaded press enter to delete the instance.
""".format(bucket))

    if wait:
        input()

    print('Deleting instance.')

    operation = delete_instance(compute, project, zone, instance_name)
    wait_for_operation(compute, project, zone, operation['name'])

if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument('project_id', help='Your Google Cloud project ID.')
    parser.add_argument(
        'bucket_name', help='Your Google Cloud Storage bucket name.')
    parser.add_argument(
        '--zone',
        default='us-central1-f',
        help='Compute Engine zone to deploy to.')
    parser.add_argument(
        '--name', default='demo-instance', help='New instance name.')

    args = parser.parse_args()

    main(args.project_id, args.bucket_name, args.zone, args.name)

Listar instâncias

Ao usar a biblioteca do cliente Python, liste instâncias usando o método compute.instances().list. Será necessário fornecer o código do projeto e a zona em que pretende listar as instâncias. Por exemplo:

def list_instances(compute, project, zone):
    result = compute.instances().list(project=project, zone=zone).execute()
    return result['items'] if 'items' in result else None

Adicionar uma instância

Para adicionar uma instância, use o método instances().insert e especifique as propriedades da nova instância. Essas propriedades são especificadas no corpo da solicitação. Para detalhes sobre cada uma delas, consulte a referência da API sobre instances.insert.

Quando você cria uma instância, os valores para as seguintes propriedades precisam ser fornecidos na solicitação:

  • Nome da instância
  • Disco permanente raiz
  • Tipo de máquina
  • Zona
  • Interfaces de rede

Este exemplo inicia uma instância com as seguintes propriedades em uma zona de sua escolha:

  • Tipo de máquina: n1-standard-1.
  • Disco permanente raiz: um novo disco permanente baseado na imagem do Debian 8 mais recente.
  • A conta de serviço padrão do Compute Engine com os seguintes escopos:

    • https://www.googleapis.com/auth/devstorage.read_write: para permitir que a instância leia e grave arquivos no Google Cloud Storage.
    • https://www.googleapis.com/auth/logging.write: para permitir que o upload de registros das instâncias seja feito no Google Cloud Logging.
  • Metadados para especificar comandos que precisam ser executados na inicialização da instância.

def create_instance(compute, project, zone, name, bucket):
    # Get the latest Debian Jessie image.
    image_response = compute.images().getFromFamily(
        project='debian-cloud', family='debian-9').execute()
    source_disk_image = image_response['selfLink']

    # Configure the machine
    machine_type = "zones/%s/machineTypes/n1-standard-1" % zone
    startup_script = open(
        os.path.join(
            os.path.dirname(__file__), 'startup-script.sh'), 'r').read()
    image_url = "http://storage.googleapis.com/gce-demo-input/photo.jpg"
    image_caption = "Ready for dessert?"

    config = {
        'name': name,
        'machineType': machine_type,

        # Specify the boot disk and the image to use as a source.
        'disks': [
            {
                'boot': True,
                'autoDelete': True,
                'initializeParams': {
                    'sourceImage': source_disk_image,
                }
            }
        ],

        # Specify a network interface with NAT to access the public
        # internet.
        'networkInterfaces': [{
            'network': 'global/networks/default',
            'accessConfigs': [
                {'type': 'ONE_TO_ONE_NAT', 'name': 'External NAT'}
            ]
        }],

        # Allow the instance to access cloud storage and logging.
        'serviceAccounts': [{
            'email': 'default',
            'scopes': [
                'https://www.googleapis.com/auth/devstorage.read_write',
                'https://www.googleapis.com/auth/logging.write'
            ]
        }],

        # Metadata is readable from the instance and allows you to
        # pass configuration from deployment scripts to instances.
        'metadata': {
            'items': [{
                # Startup script is automatically executed by the
                # instance upon startup.
                'key': 'startup-script',
                'value': startup_script
            }, {
                'key': 'url',
                'value': image_url
            }, {
                'key': 'text',
                'value': image_caption
            }, {
                'key': 'bucket',
                'value': bucket
            }]
        }
    }

    return compute.instances().insert(
        project=project,
        zone=zone,
        body=config).execute()

As seções a seguir descrevem os parâmetros de criação de instâncias.

Discos permanentes raiz

Todas as instâncias devem ser inicializadas a partir de um disco permanente raiz. Esse disco contém todos os arquivos necessários para iniciar uma instância. Ao criar um disco permanente, especifique a imagem do SO de origem a ser aplicado no disco. No exemplo acima, foi criado um novo disco permanente raiz com base no Debian 8 junto com a instância. Entretanto, também crie um disco com antecedência e anexe-o à instância.

Metadados de instância

Ao criar sua instância, talvez você queira incluir metadados de instância, como um script de inicialização, variáveis de configuração e chaves ssh. No exemplo acima, você usou o campo metadata no corpo da solicitação para especificar um script de inicialização para a instância, além de algumas variáveis de configuração como pares de chave-valor. O script de inicialização, listado abaixo, mostra como a leitura dessas variáveis deve ser feita, como usá-las para aplicar texto em uma imagem e fazer o upload delas para o Google Cloud Storage.

apt-get update
apt-get -y install imagemagick

# Use the metadata server to get the configuration specified during
# instance creation. Read more about metadata here:
# https://cloud.google.com/compute/docs/metadata#querying
IMAGE_URL=$(curl http://metadata/computeMetadata/v1/instance/attributes/url -H "Metadata-Flavor: Google")
TEXT=$(curl http://metadata/computeMetadata/v1/instance/attributes/text -H "Metadata-Flavor: Google")
CS_BUCKET=$(curl http://metadata/computeMetadata/v1/instance/attributes/bucket -H "Metadata-Flavor: Google")

mkdir image-output
cd image-output
wget $IMAGE_URL
convert * -pointsize 30 -fill white -stroke black -gravity center -annotate +10+40 "$TEXT" output.png

# Create a Google Cloud Storage bucket.
gsutil mb gs://$CS_BUCKET

# Store the image in the Google Cloud Storage bucket and allow all users
# to read it.
gsutil cp -a public-read output.png gs://$CS_BUCKET/output.png

Excluir uma instância

Para excluir uma instância, chame o método instances().delete e forneça o nome, a zona e o código do projeto da instância a ser excluída. Como você definiu o parâmetro autoDelete para o disco de inicialização, esse parâmetro também é excluído juntamente com a instância. Essa configuração está desativada por padrão, porém é útil quando seu caso de uso faz chamadas para excluir discos e instâncias simultaneamente.

def delete_instance(compute, project, zone, name):
    return compute.instances().delete(
        project=project,
        zone=zone,
        instance=name).execute()

Executar o exemplo

Execute a amostra completa fazendo o download do código e executando-o na linha de comando. Certifique-se de fazer o download do arquivo create_instance.py e do arquivo startup-script.sh. Para executar a amostra:

python create_instance.py --name [INSTANCE_NAME] --zone [ZONE] [PROJECT_ID] [CLOUD_STORAGE_BUCKET]

em que:

  • [INSTANCE_NAME] é o nome da instância a ser criada.
  • [ZONE] é a zona pretendida para esta solicitação.
  • [PROJECT_ID] é o código do nosso projeto.
  • [CLOUD_STORAGE_BUCKET] é o nome do intervalo que você configurou inicialmente, mas sem o prefixo gs://.

Por exemplo:

python python-example.py --name example-instance --zone us-central1-a example-project my-gcs-bucket

Aguardar a conclusão de operações

As solicitações feitas à API Google Compute Engine que modificam recursos, tais como instâncias, retornarão imediatamente uma resposta confirmando sua solicitação. Essa confirmação permitirá verificar o status da operação solicitada. Como as operações podem levar alguns minutos para serem concluídas, geralmente é mais fácil esperar a operação ser concluída antes de continuar. Este método auxiliar aguardará até que a operação seja concluída antes de retornar:

def wait_for_operation(compute, project, zone, operation):
    print('Waiting for operation to finish...')
    while True:
        result = compute.zoneOperations().get(
            project=project,
            zone=zone,
            operation=operation).execute()

        if result['status'] == 'DONE':
            print("done.")
            if 'error' in result:
                raise Exception(result['error'])
            return result

        time.sleep(1)

Como fazer a limpeza

Para evitar cobranças dos recursos usados neste tutorial na conta do Google Cloud Platform:

Excluir o intervalo do Cloud Storage

Para excluir um intervalo do Google Cloud Storage:

  1. No Console do GCP, acesse o navegador do Cloud Storage.

    Acessar o navegador do Cloud Storage

  2. Marque a caixa de seleção ao lado do intervalo que você quer excluir.
  3. Para excluir o intervalo, clique no botão Excluir no topo da página.

A seguir

  • Faça o download e veja a amostra de código completo. A amostra completa contém um pequeno exemplo de como usar todos esses métodos juntos. Sinta-se à vontade para fazer o download desse exemplo, alterá-lo e executá-lo para atender às suas necessidades.
  • Leia a referência da API para aprender a executar outras tarefas com ela.
  • Comece a criar seus aplicativos.
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Compute Engine