ali_oss_object - Manage object in OSS¶

New in version 1.5.0.

Synopsis
- Requirements
Parameters
Notes
Examples
Return Values
Status
- Author

Synopsis ¶

This module allows the user to manage OSS objects within bucket. Includes support for uploading and downloading objects, retrieving object keys.

Requirements ¶

The below requirements are needed on the host that executes this module.

footmark >= 1.1.16
python >= 2.6

Parameters ¶

Parameter	Choices/Defaults	Comments
alicloud_access_key		Aliyun Cloud access key. If not set then the value of environment variable `ALICLOUD_ACCESS_KEY`, `ALICLOUD_ACCESS_KEY_ID` will be used instead. aliases: access_key_id, access_key
alicloud_region		The Aliyun Cloud region to use. If not specified then the value of environment variable `ALICLOUD_REGION`, `ALICLOUD_REGION_ID` will be used instead. aliases: region, region_id
alicloud_secret_key		Aliyun Cloud secret key. If not set then the value of environment variable `ALICLOUD_SECRET_KEY`, `ALICLOUD_SECRET_ACCESS_KEY` will be used instead. aliases: secret_access_key, secret_key
alicloud_security_token		The Aliyun Cloud security token. If not specified then the value of environment variable `ALICLOUD_SECURITY_TOKEN` will be used instead. aliases: security_token
bucket required		Bucket name.
byte_range		The range of object content that would be download. Its format like 1-100 that indicates range from one to hundred bytes of object. aliases: range
content		The object content that will be upload. It is conflict with 'file_name' when mode is 'put'.
file_name		The name of file that used to upload or download object. aliases: file
headers		Custom headers for PUT or GET operation, as a dictionary of 'key=value' and 'key=value,key=value'.
mode required	Choices: get put delete list	Switches the module behaviour between put (upload), get (download), list (list objects) and delete (delete object).
object required		Name to object after uploaded to bucket aliases: key, object_name
overwrite bool	Choices: no ← yes	Force overwrite specified object content when putting object. If it is true/false, object will be normal/appendable. Appendable Object can be convert to Noraml by setting overwrite to true, but conversely, it won't be work.
permission	Choices: private ← public-read public-read-write	This option lets the user set the canned permissions on the objects that are put. The permissions that can be set are 'private', 'public-read', 'public-read-write'. aliases: acl

Notes ¶

Note

If parameters are not set within the module, the following environment variables can be used in decreasing order of precedence ALICLOUD_ACCESS_KEY or ALICLOUD_ACCESS_KEY_ID, ALICLOUD_SECRET_KEY or ALICLOUD_SECRET_ACCESS_KEY, ALICLOUD_REGION or ALICLOUD_REGION_ID, ALICLOUD_SECURITY_TOKEN
ALICLOUD_REGION or ALICLOUD_REGION_ID can be typically be used to specify the ALICLOUD region, when required, but this can also be configured in the footmark config file

Examples ¶

# basic provisioning example to upload a content
- name: simple upload to bucket
  hosts: localhost
  connection: local
  vars:
    alicloud_access_key: <your-alicloud-access-key-id>
    alicloud_secret_key: <your-alicloud-access-secret-key>
    alicloud_region: cn-hangzhou
    mode: put
    bucket: bucketname
    content: 'Hello world! I come from alicloud.'
    object: 'remote_file.txt'
    headers:
      Content-Type: 'text/html'
      Content-Encoding: md5
  tasks:
    - name: simple upload to bucket
      ali_oss_object:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        mode: '{{ mode }}'
        bucket: '{{ bucket }}'
        content: '{{ content }}'
        headers: '{{ headers }}'
      register: result
    - debug: var=result

# basic provisioning example to upload a file
- name: simple upload to bucket
  hosts: localhost
  connection: local
  vars:
    alicloud_access_key: <your-alicloud-access-key-id>
    alicloud_secret_key: <your-alicloud-access-secret-key>
    alicloud_region: cn-hangzhou
    mode: put
    bucket: bucketname
    file_name: 'test_oss.yml'
    object: 'remote_file.txt'
    headers:
      Content-Type: 'text/html'
      Content-Encoding: md5
  tasks:
    - name: simple upload to bucket
      ali_oss_object:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        mode: '{{ mode }}'
        file_name: '{{ file_name }}'
        content: '{{ content }}'
        headers: '{{ headers }}'
      register: result
    - debug: var=result

# basic provisioning example to download a object
- name: simple upload to bucket
  hosts: localhost
  connection: local
  vars:
    alicloud_access_key: <your-alicloud-access-key-id>
    alicloud_secret_key: <your-alicloud-access-secret-key>
    alicloud_region: cn-hangzhou
    mode: get
    bucket: bucketname
    download: 'my_test.json'
    byte_range: 0-100
    object: 'remote_file.txt'
    headers:
      Content-Type: 'text/html'
      Content-Encoding: md5
  tasks:
    - name: simple upload to bucket
      ali_oss_object:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        mode: '{{ mode }}'
        file_name: '{{ download }}'
        byte_range: '{{ byte_range }}'
        content: '{{ content }}'
        headers: '{{ headers }}'
      register: result
    - debug: var=result

# basic provisioning example to list bucket objects
- name: list bucket objects
  hosts: localhost
  connection: local
  vars:
    alicloud_access_key: <your-alicloud-access-key-id>
    alicloud_secret_key: <your-alicloud-access-secret-key>
    alicloud_region: cn-hangzhou
    mode: list
    bucket: bucketname
  tasks:
    - name: list bucket objects
      ali_oss_object:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        mode: '{{ mode }}'
        bucket: '{{ bucket }}'
      register: list_result
    - debug: var=list_result

# basic provisioning example to delete bucket object
- name: delete bucket objects
  hosts: localhost
  connection: local
  vars:
    alicloud_access_key: <your-alicloud-access-key-id>
    alicloud_secret_key: <your-alicloud-access-secret-key>
    alicloud_region: cn-hangzhou
    mode: delete
    bucket: bucketname
    object: 'remote_file.txt'
  tasks:
    - name: delete bucket objects
      ali_oss_object:
        alicloud_access_key: '{{ alicloud_access_key }}'
        alicloud_secret_key: '{{ alicloud_secret_key }}'
        alicloud_region: '{{ alicloud_region }}'
        mode: '{{ mode }}'
        bucket: '{{ bucket }}'
        object: '{{ object }}'
      register: delete_object_result
    - debug: var=delete_object_result

Return Values ¶

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
changed bool	when success	current operation whether changed the resource Sample: True
key bool	expect list	the name of oss object Sample: True
object dict	on put or get	the object's information Sample: {'last_modified': '2017-07-24 19:43:41', 'next_append_position': 11, 'etag': 'A57B09D4A76BCF486DDD755900000000', 'key': 'newobject-2', 'storage_class': 'Standard', 'type': 'Appendable', 'size': '11 B'}
objects list	when list	the list all objects that has the prefix of 'object' value in the specified bucket Sample: [{'last_modified': '2017-07-24 19:42:46', 'etag': '54739B1D5AEBFD38C83356D8A8A3EDFC', 'key': 'newobject-1', 'storage_class': 'Standard', 'type': 'Normal', 'size': '2788 B'}, {'last_modified': '2017-07-24 19:48:28', 'next_append_position': 5569, 'etag': 'EB8BDADA044D58D58CDE755900000000', 'key': 'newobject-2', 'storage_class': 'Standard', 'type': 'Appendable', 'size': '5569 B'}]

Status ¶

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Author ¶

He Guimin (@xiaozhu36)

Hint

If you notice any issues in this documentation you can edit this document to improve it.