Como usar a biblioteca de cliente do Python

---

Veja neste tutorial como usar a biblioteca de cliente das APIs do Google para Python para chamar as APIs REST do AI Platform Training nos seus aplicativos em Python. Os snippets e exemplos de código no restante desta documentação usam essa biblioteca de cliente do Python.

Você também criará um modelo no seu projeto do Google Cloud. Trata-se de uma tarefa simples, facilmente desenvolvida como um pequeno exemplo.

Objetivos

Este é um tutorial básico, elaborado para você se familiarizar com a biblioteca de cliente do Python. Depois de terminá-lo, será possível executar as seguintes tarefas:

• Conseguir uma representação em Python dos serviços do AI Platform.
• Usar essa representação para criar um modelo no projeto, que ajudará a chamar as outras APIs de gerenciamento de modelos e jobs.

Observação: os exemplos de código neste tutorial usam Python 2.7. Escolha o Python 2.7 ou o Python 3 para usar com o AI Platform Training. Veja como especificar uma versão do Python para treinamentos.

Custos

Você não será cobrado pelas operações executadas neste tutorial. Consulte a página de preços para saber mais.

Antes de começar

Configurar o projeto GCP

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the AI Platform Training & Prediction and Compute Engine APIs.

   Enable the APIs

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the AI Platform Training & Prediction and Compute Engine APIs.

   Enable the APIs

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

Configurar a autenticação

Para configurar a autenticação, crie uma chave da conta de serviço e defina uma variável de ambiente para o caminho do arquivo dessa chave.

1. Crie uma conta de serviço:

   1. No Console do Google Cloud, acesse a página Criar conta de serviço.

      Acesse "Criar conta de serviço"

   2. No campo Nome da conta de serviço, insira um nome.
   3. Opcional: no campo Descrição da conta de serviço, digite uma descrição.
   4. Clique em Criar.
   5. Clique no campo Selecionar um papel. Em Todos os papéis, selecione AI Platform > Administrador do AI Platform.
   6. Clique em Adicionar outro papel.

   7. Clique no campo Selecionar um papel. Em Todos os papéis, selecione Armazenamento > Administrador de objetos do Storage.

      Observação: os papéis selecionados permitem que a conta de serviço acesse recursos. É possível ver e alterar esses papéis mais tarde no console do Google Cloud. Se estiver desenvolvendo um aplicativo de produção, talvez seja necessário especificar papéis com menos permissões que o administrador do ML Engine e o administrador de objetos do Storage. Para mais informações, consulte controle de acesso para o AI Platform Training.

   8. Clique em Concluído para criar a conta de serviço.

      Não feche a janela do navegador. Você vai usá-la na próxima etapa.

2. Crie uma chave da conta de serviço para autenticação:

   1. No console do Google Cloud, clique no endereço de e-mail da conta de serviço que você criou.
   2. Clique em Chaves.
   3. Clique em Adicionar chave e, depois, em Criar nova chave.
   4. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
   5. Clique em Fechar.

3. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço. Essa variável aplica-se apenas à sessão de shell atual. Portanto, se você abrir uma nova sessão, defina a variável novamente.

   Exemplo: Linux ou macOS

   Substitua [PATH] pelo caminho do arquivo JSON que contém a chave da conta de serviço.

   export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

   Exemplo:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Exemplo: Windows

   Substitua [PATH] pelo caminho do arquivo JSON que contém a chave da conta de serviço, e [FILE_NAME] pelo nome de arquivo.

   Com o PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

   Por exemplo:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"

   Com o prompt de comando:

   set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

Configurar um ambiente de desenvolvimento em Python

Escolha uma das opções abaixo para configurar o ambiente localmente no macOS ou em um ambiente remoto no Cloud Shell.

Para usuários do macOS, recomendamos a configuração do ambiente usando a guia MACOS abaixo. O Cloud Shell, mostrado na guia CLOUD SHELL, está disponível para macOS, Linux e Windows. Com ele, você testa rapidamente o AI Platform Training. No entanto, ele não é adequado para trabalhos de desenvolvimento contínuos.

macOS

1. Verificar a instalação do Python
   Verifique se o Python (em inglês) está instalado e, se necessário, instale-o.

   python -V

2. Verificar a pip instalação do
   pip é o gerenciador de pacote do Python, incluído nas versões atuais do Python. Execute pip --version para verificar se o pip já está instalado. Caso contrário, veja como instalar o pip (em inglês).

   É possível fazer upgrade do pip usando o comando a seguir:

   pip install -U pip

   Consulte a documentação do pip para mais detalhes.

3. Instalar virtualenv
virtualenv é uma ferramenta para criar ambientes Python isolados. Execute virtualenv --version para verificar se a virtualenv já está instalada. Caso contrário, instale virtualenv (em inglês):

   pip install --user --upgrade virtualenv

   Para criar um ambiente de desenvolvimento isolado para este guia, crie um novo ambiente virtual em virtualenv. Por exemplo, com o comando a seguir, você ativa um ambiente chamado aip-env:

   virtualenv aip-env
   source aip-env/bin/activate

4. Neste tutorial, execute o restante dos comandos no ambiente virtual.

   Veja mais informações sobre o uso da virtualenv (em inglês). Para sair da virtualenv, execute deactivate.

Cloud Shell

1. Abra o console do Google Cloud.

   Console do Google Cloud

2. Clique no botão Ativar o Cloud Shell na parte superior da janela do console.

   

   Uma sessão do Cloud Shell é aberta em um novo frame na parte inferior do console e um prompt de linha de comando é exibido. A inicialização da sessão do shell pode levar alguns segundos.

   

   A sessão do Cloud Shell está pronta para ser usada.

3. Configure a ferramenta de linha de comando gcloud para usar o projeto selecionado.

   gcloud config set project [selected-project-id]

   em que [selected-project-id] é o ID do projeto. Retire os colchetes incluídos.

Instale a biblioteca de cliente da API do Google para Python.

Instale a biblioteca de cliente da API do Google para Python.

Este é um tutorial básico, elaborado para você se familiarizar com a biblioteca de cliente do Python. Depois de terminá-lo, será possível executar as seguintes tarefas:

• Conseguir uma representação em Python dos serviços do AI Platform.
• Usar essa representação para criar um modelo no projeto, que ajudará a chamar as outras APIs de gerenciamento de modelos e jobs.

Observação: os exemplos de código neste tutorial usam Python 2.7. Escolha o Python 2.7 ou o Python 3 para usar com o AI Platform Training. Veja como especificar uma versão do Python para treinamentos.

Você não receberá cobranças pelas operações executadas neste tutorial. Consulte a página de preços para saber mais.

Como importar os módulos necessários

Quando você quiser usar a biblioteca de cliente das APIs do Google para Python a fim de chamar as APIs REST do AI Platform Training no seu código, importe o respectivo pacote e o pacote OAuth2. Para este tutorial (e para a maioria dos usos padrão do AI Platform Training), será preciso apenas importar módulos específicos:

• GoogleCredentials do OAuth2
• discovery da biblioteca de cliente da API do Google para Python.
• errors da biblioteca de cliente da API do Google para Python

Consulte a documentação desses pacotes para saber mais sobre outros módulos disponíveis.

Crie um arquivo Python usando o editor que preferir e adicione estas linhas:

from oauth2client.client import GoogleCredentials
from googleapiclient import discovery
from googleapiclient import errors

Como criar uma representação em Python da API

Consiga a representação Python da API REST. Você chama o método build porque a biblioteca de cliente da API usa a descoberta de serviço para configurar dinamicamente as conexões com os serviços que já existem quando a chamada é feita. Chame o objeto que encapsula os serviços ml:

ml = discovery.build('ml','v1')

Como configurar os parâmetros e o corpo da solicitação

Para fazer uma chamada para um serviço, crie os parâmetros e o corpo da solicitação que serão informados à API REST. Informe os parâmetros como parâmetros regulares do Python para o método que representa a chamada. O corpo é um recurso JSON, igual ao que você usaria se chamasse diretamente a API com uma solicitação HTTP.

Observe a API REST para criar um modelo em uma nova guia do navegador, projects.models.create:

• Observe o parâmetro de caminho parent, que é a parte do URI da solicitação que identifica o projeto. Se estiver fazendo a solicitação HTTP POST diretamente, você usará o seguinte URI:

  https://ml.googleapis.com/v1/projects/YOUR_PROJECT_ID/models

  Quando você usa a biblioteca de cliente da API, a parte variável do URI é representada como um parâmetro do tipo string para a chamada da API. Defina-o como 'projects/<var>YOUR_PROJECT_ID</var>'. Armazene o projeto em uma variável para tornar as chamadas da API mais limpas:

  project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

• O corpo da solicitação é um recurso JSON que representa a informação do modelo. Observe que há dois valores de entrada na definição de recurso do modelo: name e description (opcional). É possível transferir um dicionário Python no lugar do JSON e a biblioteca de cliente da API realizará a conversão necessária.

  Para criar o dicionário Python:

  request_dict = {'name': 'your-model-name',
                 'description': 'This is a machine learning model entry.'}

Como criar a solicitação

As chamadas para APIs com a biblioteca cliente Python têm duas etapas: primeiro, você cria uma solicitação, depois, você a usa para fazer a chamada.

Criar a solicitação

Use os objetos cliente que criou anteriormente como a raiz da hierarquia da API e especifique a API que você quer usar. Se tiver seguido exatamente o snippet de código, o objeto se chama ml. Cada coleção no caminho da API se comporta como uma função que retorna uma lista das coleções e métodos existentes na API. Por exemplo, a raiz de todas as APIs do AI Platform Training é projects, portanto, a chamada começa com ml.projects().

Use este código para criar a solicitação:

request = ml.projects().models().create(parent=project_id, body=request_dict)

Enviar a solicitação

A solicitação criada na última etapa expõe um método execute que é chamado para enviar a solicitação ao serviço:

response = request.execute()

É comum que os desenvolvedores combinem esta etapa com a última:

response = ml.projects().models().create(parent=project_id,
                                         body=request_dict).execute()

Lidar com erros simples

Muitas coisas podem dar errado quando você faz chamadas de API pela Internet. É importante saber lidar com os erros mais comuns. A maneira mais simples de fazer isso é colocar sua solicitação em um bloco try e capturar prováveis erros. A maioria dos erros que você provavelmente receberá do serviço é de HTTP, encapsulados na classe HttpError. Para detectar esses erros, use o módulo errors do pacote googleapiclient.

Encapsule a chamada request.execute() em um bloco try. Para imprimir a resposta de uma chamada bem-sucedida, insira também uma declaração print no bloco:

try:
    response = request.execute()
    print(response)

Por fim, adicione um bloco de detecção para processar os erros HTTP. É possível usar HttpError._get_reason() para receber os campos de texto de razão da resposta:

except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

No entanto, uma declaração impressa simples pode não ser a abordagem correta para seu aplicativo.

Como realizar o funcionamento em conjunto

Veja o exemplo completo:

from googleapiclient import discovery
from googleapiclient import errors

# Store your full project ID in a variable in the format the API needs.
project_id = 'projects/{}'.format('YOUR_PROJECT_ID')

# Build a representation of the Cloud ML API.
ml = discovery.build('ml', 'v1')

# Create a dictionary with the fields from the request body.
request_dict = {'name': 'your_model_name',
               'description': 'your_model_description'}

# Create a request to call projects.models.create.
request = ml.projects().models().create(
              parent=project_id, body=request_dict)

# Make the call.
try:
    response = request.execute()
    print(response)
except errors.HttpError, err:
    # Something went wrong, print out some information.
    print('There was an error creating the model. Check the details:')
    print(err._get_reason())

Como generalizar para outros métodos

É possível usar o procedimento aprendido aqui para fazer qualquer chamada da API. REST Algumas das APIs exigem recursos JSON muito mais complicados que a criação de um modelo, mas os princípios são os mesmos:

1. Importe googleapiclient.discovery e googleapiclient.errors.

2. Use o módulo de descoberta para criar uma representação Python da API.

3. Use a representação da API como uma série de objetos aninhados para chegar à API que você quer e criar uma solicitação. Por exemplo,

   request = ml.projects().models().versions().delete(
       name='projects/myproject/models/mymodel/versions/myversion')

4. Chame request.execute() para enviar a solicitação, lidando com as exceções da forma adequada ao aplicativo.

5. Quando há um corpo de resposta, é possível tratá-lo como um dicionário Python e conseguir os objetos JSON especificados na referência da API. Muitos dos objetos nas respostas têm campos que estão presentes apenas em algumas circunstâncias. Verifique sempre para evitar erros de chave:

   response = request.execute()
   
   some_value = response.get('some_key') or 'default_value'

A seguir

• Confira arquiteturas de referência, diagramas, tutoriais e práticas recomendadas do Google Cloud. Confira o Centro de arquitetura do Cloud.
• Conheça melhor a API AI Platform Training.
• Saiba como gerenciar modelos na visão geral de gerenciamento de modelos e jobs.