Object Storage Service:Interroger des objets à l'aide du SDK OSS pour Python 1.0

Notes

• Dans cette rubrique, le point de terminaison public de la région Chine (Hangzhou) est utilisé. Si vous souhaitez accéder à OSS depuis d'autres services Alibaba Cloud situés dans la même région que OSS, utilisez un point de terminaison interne. Pour plus d'informations sur les régions et les points de terminaison OSS, consultez Régions et points de terminaison.

• Cette rubrique illustre la création d'une instance OSSClient avec un point de terminaison OSS. Pour d'autres configurations, telles que l'utilisation d'un domaine personnalisé ou l'authentification via des identifiants du Security Token Service (STS), consultez Initialisation.

• Pour interroger des objets, vous devez disposer de l'autorisation oss:GetObject. Pour plus d'informations, consultez Accorder une politique personnalisée.

• Seuls les objets aux formats CSV et JSON peuvent être interrogés à l'aide de SelectObject.

Exemples

Le code suivant montre comment interroger des objets CSV et JSON :

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def select_call_back(consumed_bytes, total_bytes =  None):
        print('Consumed Bytes:' + str(consumed_bytes) + '\n')

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"

# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

key ='python_select.csv'
content ='Tom Hanks,USA,45\r\n'*1024
filename ='python_select.csv'

# Upload a CSV file. 
bucket.put_object(key, content)
# Configure the parameters for the SelectObject operation. 
csv_meta_params = {'RecordDelimiter': '\r\n'}
select_csv_params = {'CsvHeaderInfo': 'None',
                    'RecordDelimiter': '\r\n',
                    'LineRange': (500, 1000)}

csv_header = bucket.create_select_object_meta(key, csv_meta_params)
print(csv_header.rows)
print(csv_header.splits)
result = bucket.select_object(key, "select * from ossobject where _3 > 44", select_call_back, select_csv_params)
select_content = result.read()
print(select_content)

result = bucket.select_object_to_file(key, filename,
      "select * from ossobject where _3 > 44", select_call_back, select_csv_params)
bucket.delete_object(key)

###JSON DOCUMENT
key =  'python_select.json'
content =  "{\"contacts\":[{\"key1\":1,\"key2\":\"hello world1\"},{\"key1\":2,\"key2\":\"hello world2\"}]}"
filename =  'python_select.json'
# Upload a JSON DOCUMENT object. 
bucket.put_object(key, content)
select_json_params = {'Json_Type': 'DOCUMENT'}
result = bucket.select_object(key, "select s.key2 from ossobject.contacts[*] s where s.key1 = 1", None, select_json_params)
select_content = result.read()
print(select_content)

result = bucket.select_object_to_file(key, filename,
      "select s.key2 from ossobject.contacts[*] s where s.key1 = 1", None, select_json_params)
bucket.delete_object(key)

###JSON LINES
key =  'python_select_lines.json'
content =  "{\"key1\":1,\"key2\":\"hello world1\"}\n{\"key1\":2,\"key2\":\"hello world2\"}"
filename =  'python_select.json'
# Upload a JSON LINES object. 
bucket.put_object(key, content)
select_json_params = {'Json_Type': 'LINES'}
json_header = bucket.create_select_object_meta(key,select_json_params)
print(json_header.rows)
print(json_header.splits)

result = bucket.select_object(key, "select s.key2 from ossobject s where s.key1 = 1", None, select_json_params)
select_content =  result.read()
print(select_content)
result = bucket.select_object_to_file(key, filename,
           "select s.key2 from ossobject s where s.key1 = 1", None, select_json_params)
bucket.delete_object(key)

Python SelectObject

Cette section décrit les éléments utilisés dans l'opération SelectObject en Python. Ces éléments incluent select_object, select_object_to_file et create_select_object_meta.

• select_object

  • Le code suivant montre comment spécifier les paramètres pour select_object :

    def select_object(self, key, sql,
                       progress_callback=None,
                       select_params=None
                       byte_range=None
                       headers=None
                       ):

    L'exemple de code ci-dessus permet d'exécuter une instruction SQL sur l'objet possédant la clé spécifiée et de renvoyer les résultats de la requête.

    • sql : l'instruction SQL qui ne doit pas être encodée en Base64.

    • Progress_callback : facultatif. Ce paramètre spécifie une fonction de rappel utilisée pour signaler la progression de la requête.

    • select_params : les paramètres et actions de l'opération SelectObject.

    • headers : les informations d'en-tête incluses dans la requête. Les informations d'en-tête fonctionnent de la même manière que pour l'opération GetObject. Par exemple, vous pouvez configurer le champ bytes dans l'en-tête de la requête pour spécifier la plage d'un objet CSV à interroger.

  • Le tableau suivant décrit les paramètres pris en charge par select_params.

    Parameter	Description
    Json_Type	Par défaut, l'objet est un objet CSV si ce paramètre n'est pas spécifié. L'objet est un objet JSON Document si ce paramètre est défini sur DOCUMENT. L'objet est un objet JSON LINES si ce paramètre est défini sur LINES.
    CsvHeaderInfo	Les informations d'en-tête de l'objet CSV. Valeurs valides : None, Ignore et Use. None : cet objet ne possède aucune information d'en-tête configurée. Ignore : cet objet possède des informations d'en-tête configurées, mais celles-ci ne sont pas utilisées lors de l'exécution de l'instruction SQL. Use : cet objet possède des informations d'en-tête configurées et les noms de colonnes figurant dans ces informations sont utilisés lors de l'exécution de l'instruction SQL.
    CommentCharacter	Le caractère de commentaire dans l'objet CSV. La valeur de ce paramètre ne peut comporter qu'un seul caractère. La valeur par défaut est None, ce qui indique qu'aucun caractère de commentaire n'est autorisé.
    RecordDelimiter	Le délimiteur de ligne dans l'objet CSV. La valeur de ce paramètre ne peut comporter qu'un ou deux caractères. Valeur par défaut : \n.
    OutputRecordDelimiter	Le délimiteur de ligne dans le résultat de sortie de l'instruction SELECT. Valeur par défaut : \n.
    FieldDelimiter	Le délimiteur de colonne dans l'objet CSV. La valeur de ce paramètre ne peut comporter qu'un seul caractère. La valeur par défaut est une virgule (,).
    OutputFieldDelimiter	Le délimiteur de colonne dans le résultat de sortie de l'instruction SELECT. La valeur par défaut est une virgule (,).
    QuoteCharacter	Le caractère de guillemet pour les colonnes dans l'objet CSV. La valeur de ce paramètre ne peut comporter qu'un seul caractère. La valeur par défaut est un guillemet double ("). Les délimiteurs de ligne et de colonne entourés de caractères de guillemet sont traités comme des caractères normaux.
    SplitRange	La plage de fractionnement dans une requête multipartie. La valeur de ce paramètre est un intervalle fermé au format (start, end), qui indique la plage de fractions à interroger.
    LineRange	La plage de lignes dans une requête multipartie. La valeur de ce paramètre est un intervalle fermé au format (start, end), qui indique la plage de lignes à interroger.
    CompressionType	Le format dans lequel l'objet est compressé. Valeurs valides : GZIP et None. Valeur par défaut : None.
    KeepAllColumns	Si ce paramètre est défini sur true, les colonnes exclues par l'instruction SELECT dans l'objet CSV restent vides dans le résultat de sortie. Toutefois, les positions des colonnes sont conservées. Valeur par défaut : False. Par exemple, les colonnes de l'objet CSV sont firstname, lastname et age. L'instruction SQL est select firstname, age from ossobject. Si KeepAllColumns est défini sur true, le résultat de sortie est firstname,,age, où une virgule supplémentaire (,) est ajoutée pour indiquer la position de la colonne lastname exclue. Si KeepAllColumns est défini sur false, le résultat de sortie est firstname,age. Remarque Ce paramètre vise à permettre au code utilisé pour traiter GetObject de traiter SelectObject sans modifications.
    OutputRawData	Si ce paramètre est défini sur True, SelectObject renvoie directement les données brutes. Si aucune donnée n'est renvoyée pendant une longue période, une erreur de délai d'attente peut se produire. Si ce paramètre est défini sur False, les données de sortie sont encapsulées dans des trames. Valeur par défaut : False.
    EnablePayloadCrc	Indique si une valeur de contrôle de redondance cyclique (CRC) est calculée pour chaque trame. Valeur par défaut : False.
    OutputHeader	Les informations d'en-tête dans la première ligne du résultat de sortie. Ce paramètre s'applique uniquement aux objets CSV.
    SkipPartialDataRecord	Si ce paramètre est défini sur True pour un objet CSV, l'enregistrement actuel est ignoré lorsqu'une colonne de cet enregistrement ne contient aucune donnée. Si ce paramètre est défini sur True pour un objet JSON, l'enregistrement actuel est ignoré lorsqu'une clé de cet enregistrement n'existe pas. Si ce paramètre est défini sur False, une colonne sans données reste vide dans le résultat de sortie. Par exemple, une ligne comprend les colonnes firstname, lastname et age. L'instruction SQL est select _1, _4 from ossobject. Si ce paramètre est défini sur True, cette ligne est ignorée. Si ce paramètre est défini sur False, firstname,\n est renvoyé.
    MaxSkippedRecordsAllowed	Le nombre maximal de lignes ignorées. La valeur par défaut est 0, ce qui indique qu'une erreur est renvoyée si une ligne est ignorée.
    ParseJsonNumberAsString	Si ce paramètre est défini sur True, tous les nombres de l'objet JSON sont analysés sous forme de chaînes. Si ce paramètre est défini sur False, tous les nombres de l'objet JSON sont analysés sous forme d'entiers ou de nombres à virgule flottante. Valeur par défaut : False. Les nombres à virgule flottante haute précision dans un objet JSON subissent une perte de précision lorsqu'ils sont analysés en tant que nombres à virgule flottante. Pour conserver la précision, vous pouvez définir ce paramètre sur True et utiliser la fonction CAST pour convertir les données analysées en type décimal.

  • Résultats renvoyés par select_object : un objet SelectObjectResult est renvoyé. Vous pouvez utiliser la fonction read() ou la méthode _iter_ pour obtenir tous les résultats.

    Remarque

    Si vous appelez la fonction read() pour lire tous les résultats lorsque plusieurs résultats sont renvoyés, des ressources mémoire excessives sont utilisées et vous devez attendre longtemps. Nous vous recommandons d'utiliser la méthode _iter_ (foreach chunk in result) pour obtenir les résultats et traiter chaque fragment des résultats. La méthode _iter_ réduit l'utilisation de la mémoire et permet au client de traiter chaque demande de fragment traitée par le serveur OSS en temps opportun. Ainsi, le client n'a pas besoin d'attendre que tous les résultats soient renvoyés.

• select_object_to_file

  def select_object_to_file(self, key, filename, sql,
                     progress_callback=None,
                     select_params=None
                     headers=None
                     ):

  L'exemple de code ci-dessus permet d'exécuter une instruction SQL sur l'objet possédant la clé spécifiée et d'écrire les résultats de la requête dans un autre objet spécifié.

  Les autres paramètres sont identiques à ceux de select_object.

• create_select_object_meta

  • Syntaxe de create_select_object_meta

    def create_select_object_meta(self, key, select_meta_params=None, header=None):

    L'exemple de code ci-dessus permet de créer des métadonnées Select Meta pour l'objet possédant la clé spécifiée ou d'obtenir des métadonnées Select Meta à partir d'un tel objet. Les métadonnées Select Meta incluent le nombre total de lignes, le nombre total de colonnes (pour les objets CSV) et le nombre total de fractions dans un objet.

    Si des métadonnées Select Meta ont déjà été créées pour un objet, cette fonction ne recrée pas les métadonnées Select Meta, sauf si le paramètre OverwriteIfExists est défini sur true.

    Pour créer des métadonnées Select Meta pour un objet, l'objet doit être entièrement analysé.

  • Le tableau suivant décrit les paramètres pris en charge par select_meta_params.

    Parameter	Description
    Json_Type	Par défaut, l'objet est un objet CSV si ce paramètre n'est pas spécifié. Si ce paramètre est spécifié, sa valeur doit être LINES, ce qui indique que l'objet est un objet JSON LINES. Remarque Cette opération ne s'applique pas aux objets JSON Document.
    RecordDelimiter	Le délimiteur de ligne dans l'objet CSV.
    FieldDelimiter	Le délimiteur de colonne dans l'objet CSV.
    QuoteCharacter	Le caractère de guillemet dans l'objet CSV. Les délimiteurs de ligne et de colonne entourés de caractères de guillemet sont traités comme des caractères normaux.
    CompressionType	Le format dans lequel l'objet est compressé. Aucun format de compression n'est pris en charge. La valeur par défaut est None.
    OverwriteIfExists	Indique si les métadonnées Select Meta créées écrasent les métadonnées Select Meta d'origine. Vous n'avez généralement pas besoin de définir ce paramètre.

  • Résultats renvoyés par create_select_object_meta : un objet GetSelectObjectMetaResult est renvoyé, qui inclut les attributs rows et splits. Pour un objet CSV, l'objet select_resp dans le résultat inclut l'attribut columns, qui indique le nombre de colonnes dans l'objet CSV.

Références

• Pour consulter l'exemple de code complet utilisé pour interroger des objets, visitez GitHub.

• Pour plus d'informations sur l'opération API que vous pouvez appeler pour interroger des objets, consultez SelectObject.