Tablestore Python SDK - Tablestore: Central de Documentação do Alibaba Cloud

O Tablestore SDK for Python oferece suporte a operações com os modelos de tabela ampla e de séries temporais.

Primeiros passos

Prepare o ambiente, instale o SDK e inicialize um client para começar.

Pré-requisitos

Baixe e instale o ambiente de execução do Python. Execute o comando python3 --version para verificar a versão do Python.

A partir da versão 6.0.0, o Python SDK suporta apenas Python 3 e não oferece mais suporte ao Python 2. Para usar Python 2, utilize a versão 5.4.4 ou anterior.

Instalar o SDK

Escolha um método de instalação. Use a versão mais recente do SDK para garantir que os exemplos de código funcionem corretamente.

Instalação via pip (recomendado)

Execute o comando a seguir para instalar o SDK.

pip3 install tablestore

Instalação a partir do GitHub

Clone o SDK do GitHub usando git e instale-o.

Clone o repositório.

git clone https://github.com/aliyun/aliyun-tablestore-python-sdk.git

Acesse o diretório do SDK.
```
cd aliyun-tablestore-python-sdk
```
Instale o SDK.
```
python3 setup.py install
```

Instalação a partir do código-fonte

Baixe e instale o SDK diretamente do código-fonte.

Baixe e descompacte o Python SDK.
Acesse o diretório do SDK descompactado.
Instale o SDK.
```
python3 setup.py install
```

Configurar credenciais de acesso

Crie uma AccessKey para sua conta Alibaba Cloud ou usuário RAM e configure-a como variável de ambiente para evitar codificar as credenciais diretamente no código.

Reinicie a IDE, o terminal, outros aplicativos de desktop e serviços em segundo plano após a configuração para carregar as variáveis de ambiente atualizadas. Para obter mais informações sobre outros tipos de credenciais de acesso, consulte Configurar credenciais de acesso .

Linux

Adicione as variáveis de ambiente ao arquivo ~/.bashrc:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

Aplique as alterações:
```
source ~/.bashrc
```

Verifique as variáveis de ambiente:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

macOS

Verifique o shell padrão:
```
echo $SHELL
```

Configure conforme o tipo de shell:

Zsh

Adicione as variáveis de ambiente ao arquivo ~/.zshrc:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

Aplique as alterações:
```
source ~/.zshrc
```

Verifique as variáveis de ambiente:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

Bash

Adicione as variáveis de ambiente ao arquivo ~/.bash_profile:

echo "export TABLESTORE_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export TABLESTORE_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

Aplique as alterações:
```
source ~/.bash_profile
```

Verifique as variáveis de ambiente:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

Windows

CMD

Defina as variáveis de ambiente no CMD:

setx TABLESTORE_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx TABLESTORE_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

Reinicie o CMD e verifique:

echo %TABLESTORE_ACCESS_KEY_ID%
echo %TABLESTORE_ACCESS_KEY_SECRET%

PowerShell

Execute no PowerShell:

[Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

Verifique as variáveis de ambiente:

[Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("TABLESTORE_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

Inicializar o client

O código a seguir inicializa um client e lista todas as tabelas de dados e de séries temporais em uma instância para validar a conectividade.

Importante

O acesso pela rede pública vem desativado por padrão em novas instâncias. Para ativá-lo, acesse Network Management da instância.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

import os
import sys
from tablestore import OTSClient

def main():
    try:
        # Get access credentials from environment variables. Ensure TABLESTORE_ACCESS_KEY_ID and TABLESTORE_ACCESS_KEY_SECRET are set.
        access_key_id = os.getenv("TABLESTORE_ACCESS_KEY_ID")
        access_key_secret = os.getenv("TABLESTORE_ACCESS_KEY_SECRET")

        # TODO: Replace the following values with your instance details.
        instance_name = "n01k********"  # Instance name
        endpoint = "https://n01k********.cn-hangzhou.ots.aliyuncs.com"  # Instance endpoint
        
        # Create a client instance.
        client = OTSClient(endpoint, access_key_id, access_key_secret, instance_name)

        # List the data tables.
        resp = client.list_table()

        print(f"Found {len(resp)} data tables in instance '{instance_name}':")
        for table_name in resp:
            print(f"{table_name}")

        # List the time series tables.
        resp = client.list_timeseries_table()

        print(f"\nFound {len(resp)} time series tables in instance '{instance_name}':")
        for tableMeta in resp:
            print(f"{tableMeta.timeseries_table_name}")
            
    except Exception as e:
        print(f"Operation failed: {str(e)}")
        sys.exit(1)

if __name__ == "__main__":
    main()

Compatibilidade de versões

A versão atual é 6.x.x. Compatibilidade com versões anteriores:

Compatível com 5.x.x.

As versões 5.4.x, 5.3.x e 5.2.x são compatíveis. As versões 5.2.1 e 5.1.0 apresentam incompatibilidades nos seguintes casos:
- Tipo de retorno do método Search.
  
  Na versão 5.1.0 e anteriores, esse método retorna uma Tuple por padrão. A partir da 5.2.0, ele retorna um objeto SearchResponse. O SearchResponse implementa __iter__ e permite iteração. Para obter uma Tuple, use SearchResponse.v1_response().
- Novo método ParallelScan.
  
  Por padrão, este método retorna um objeto ParallelScanResponse. Para obter uma Tuple, use ParallelScanResponse.v1_response().
Compatível com 4.x.x.
Incompatível com 2.x.x. A série 2.x.x aceita chaves primárias fora de ordem, enquanto a 4.0.0 e posteriores não. Alterações disruptivas:
- Nome do pacote alterado de ots2 para tablestore.
- Parâmetro TableOptions adicionado a Client.create_table.
- Em put_row, get_row e update_row, o tipo de primary_key mudou de dict para list para preservar a ordem da chave primária.
- Para put_row e update_row, o tipo de attribute_columns passou de dict para list.
- Campo timestamp incluído em attribute_columns para put_row e update_row.
- get_row e get_range agora exigem pelo menos um dos parâmetros: max_version and time_range.
- Os métodos put_row, update_row e delete_row passaram a suportar return_type. O único valor aceito é RT_PK, que devolve a chave primária (PK) da linha.
- As operações put_row, update_row e delete_row incluem agora return_row na resposta. Quando return_type está definido como RT_PK, return_row contém o valor da PK.

Perguntas frequentes

O que fazer se ocorrer o erro "Signature mismatch"?

A seguinte exceção é exibida:

Error Code: OTSAuthFailed, Message: Signature mismatch., RequestId: 0005f55a-xxxx-xxxx-xxxx-xxxxxxxxxxxx, TraceId: 10b0f0e0-xxxx-xxxx-xxxx-xxxxxxxxxxxx, HttpStatus: 403

Causa: A AccessKey ID ou o AccessKey secret está incorreto.
Solução: Forneça a AccessKey ID e o AccessKey secret corretos.

O que fazer se ocorrer o erro "Request denied by instance ACL policies"?

O SDK pode retornar o erro Request denied by instance ACL policies:

[ErrorCode]:OTSAuthFailed, [Message]:Request denied by instance ACL policies., [RequestId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [TraceId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [HttpStatus:]403

Causa: O tipo de rede do client não corresponde à política de acesso da instância. Por exemplo, a instância não permite acesso pela internet.
Solução: O acesso à rede pública é desativado por padrão. Para habilitá-lo:
1. No console do Tablestore, clique em a instância desejada.
2. Clique em Network Management. Em Allowed Network Type, selecione Internet e clique em Settings.

O que fazer se ocorrer o erro "Request denied because this instance can only be accessed from the binded VPC"?

O SDK pode apresentar o erro Request denied because this instance can only be accessed from the bound VPC:

[ErrorCode]:OTSAuthFailed, [Message]:Request denied because this instance can only be accessed from the binded VPC., [RequestId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [TraceId]:XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, [HttpStatus:]403

Causa: O tipo de acesso da instância está configurado como Bound VPCs Only ou Tablestore Console or Bound VPCs, mas o client não está em uma VPC vinculada ou não acessa o Tablestore por meio de um endpoint de VPC.
Solução: Permita o acesso pela internet ou vincule uma VPC e conecte o client a partir dela:
1. No console do Tablestore, clique em a instância alvo.
2. Clique em Network Management > Bind VPC. Selecione um VPC ID e um VSwitch, insira um VPC Name e clique em OK.

Como acessar recursos do Tablestore via HTTPS?

Use a versão mais recente do Python SDK. Certifique-se de que sua versão do OpenSSL seja 0.9.8j ou superior. Recomenda-se o OpenSSL 1.0.2d.

O que fazer em caso de incompatibilidade de versões do protobuf?

Algumas versões do protobuf são incompatíveis com os arquivos *pb2.py do pacote de instalação. Para resolver, regenere os arquivos *pb2.py:

Use a versão atual do protoc para gerar o código dos arquivos proto.

protoc --python_out=. tablestore/protobuf/search.proto
protoc --python_out=. tablestore/protobuf/table_store.proto
protoc --python_out=. tablestore/protobuf/table_store_filter.proto

Renomeie os arquivos gerados com a extensão pb2.py e copie-os para tablestore/protobuf/ no diretório de instalação, substituindo os arquivos *pb2.py originais.

Usar a ferramenta Credentials para ler credenciais de acesso

Execute o comando a seguir para instalar o pacote alibabacloud_credentials.
```
pip3 install alibabacloud_credentials
```
Configure as variáveis de ambiente.

Defina ALIBABA_CLOUD_ACCESS_KEY_ID e ALIBABA_CLOUD_ACCESS_KEY_SECRET com a AccessKey ID e o AccessKey secret da sua conta Alibaba Cloud.

Leia as credenciais de acesso.

O código a seguir lê as credenciais de acesso das variáveis de ambiente utilizando a ferramenta Credentials.

# -*- coding: utf-8 -*-
from alibabacloud_credentials.client import Client as CredClient

# Use CredClient to get the AccessKey ID and AccessKey secret from the environment variables.
cred = CredClient()
access_key_id = cred.get_credential().access_key_id
access_key_secret = cred.get_credential().access_key_secret

Referências

Tratamento de falhas