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.

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.

    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.

    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.

    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.

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.

    Ativa o Google Cloud Shell

    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.

    Seção do Cloud Shell

    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.
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:

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. Você pode ver no definição de recurso do modelo que ela tem dois valores de entrada: name e (opcionalmente) description. É 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