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

O SDK do Tablestore para Python oferece suporte a operações de modelo de tabela ampla e de séries temporais.

Primeiros passos

Prepare seu 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 SDK para Python oferece suporte apenas ao Python 3 e não é mais compatível com o Python 2. Para usar o Python 2, utilize a versão 5.4.4 ou anterior.

Instale o SDK

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

Instale usando pip (recomendado)

Execute o comando a seguir para instalar o SDK.

pip3 install tablestore

Instale 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
```

Instale a partir do código-fonte

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

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

Configure credenciais de acesso

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

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

Linux

Adicione as variáveis de ambiente ao ~/.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
```

Confirme as variáveis de ambiente:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

macOS

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

Configure de acordo com o tipo de shell:

Zsh

Adicione as variáveis de ambiente ao ~/.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
```

Confirme as variáveis de ambiente:

echo $TABLESTORE_ACCESS_KEY_ID
echo $TABLESTORE_ACCESS_KEY_SECRET

Bash

Adicione as variáveis de ambiente ao ~/.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
```

Confirme 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)

Confirme as variáveis de ambiente:

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

Inicialize o client

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

Importante

O acesso pela rede pública está 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 entre si. As versões 5.2.1 e 5.1.0 são incompatíveis nos seguintes casos:
- Tipo de retorno do método Search.
  
  Na versão 5.1.0 e anteriores, esse método retorna um Tuple por padrão. A partir da versão 5.2.0, ele retorna um objeto SearchResponse. O SearchResponse implementa __iter__ e suporta iteração. Para obter um Tuple, use SearchResponse.v1_response().
- O novo método ParallelScan.
  
  Por padrão, esse método retorna um objeto ParallelScanResponse. Para obter um 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 versão 4.0.0 e posteriores não aceitam. Alterações incompatíveis:
- O nome do pacote mudou de ots2 para tablestore.
- O parâmetro TableOptions foi adicionado ao Client.create_table.
- Em put_row, get_row e update_row, o tipo de primary_key mudou de dict para list a fim de preservar a ordem das chaves primárias.
- Em put_row e update_row, o tipo de attribute_columns mudou de dict para list.
- O campo timestamp foi adicionado a attribute_columns em put_row e update_row.
- get_row e get_range agora exigem pelo menos um entre max_version and time_range.
- put_row, update_row e delete_row agora suportam return_type. O único valor aceito é RT_PK, que retorna a chave primária (PK) da linha.
- put_row, update_row e delete_row agora incluem return_row na resposta. Quando return_type está definido como RT_PK, return_row contém o valor de PK.

Perguntas frequentes

O que fazer quando ocorre o erro "Signature mismatch"?

A seguinte exceção ocorre:

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

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

O que fazer quando ocorre 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 pela rede pública está desativado por padrão. Para ativá-lo:
1. No console do Tablestore, clique na instância desejada.
2. Clique em Network Management. Em Allowed Network Type, selecione Internet e clique em Settings.

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

O SDK pode retornar 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á definido como Bound VPCs Only ou Tablestore Console or Bound VPCs, mas o client não está em uma VPC vinculada ou não está acessando 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 na instância desejada.
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 SDK para Python. Certifique-se de que sua versão do OpenSSL seja 0.9.8j ou posterior. A versão recomendada é OpenSSL 1.0.2d.

O que fazer quando as versões do protobuf são incompatíveis?

Algumas versões do protobuf são incompatíveis com os arquivos *pb2.py presentes no pacote de instalação. Para resolver isso, gere novamente 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 o 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 a partir das variáveis de ambiente usando 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