amigocloud 1.2.5

认证

此库使用API令牌进行认证。要生成或访问您的API令牌，请访问 API令牌。

from amigocloud import AmigoCloud
amigocloud = AmigoCloud(token='R:dlNDEiOWciP3y26kG2cHklYpr2HIPK40HD32r1')

您还可以使用项目令牌。请记住，项目令牌只能用于查询属于其项目相关的端点。如果项目URL与项目不匹配，将抛出 AmigoCloudError。

from amigocloud import AmigoCloud
amigocloud = AmigoCloud(token='C:Ndl3xGWeasYt9rqyuVsByf5HPMAGyte10y1Mub',
                        project_url='users/123/projects/1234')

如果您只想进行不会更改数据的请求，则可以使用READ令牌。否则，您需要使用更宽泛的令牌。

请求

登录后，您可以开始向服务器发送请求。您可以使用完整的URL或相对API URL。

# All three will do the same request:
amigocloud.get('me')
amigocloud.get('/me')
amigocloud.get('https://www.amigocloud.com/api/v1/me')

为了方便，当使用项目令牌时，URL相对于项目的URL（除非它以 / 开头）。

# All three will do the same request:
amigocloud.get('datasets')
amigocloud.get('/users/123/projects/1234/datasets')
amigocloud.get('https://www.amigocloud.com/api/v1/users/123/projects/1234/datasets')

从Python创建新的AmigoCloud项目非常简单

data = {'name': 'New Project', 'description': 'Created from Python'}
amigocloud.post('me/projects', data)

所有响应都解析为JSON并返回Python对象（通常是dict）。这些数据可以稍后用于其他请求。

me = amigocloud.get('me')
visible_projects = amigocloud.get(me['visible_projects'])

print 'My projects:'
for project in visible_projects['results']:
    print '*', project['name']

如果您想获取原始响应，可以使用 raw 参数。

me = amigocloud.get('me')
images = amigocloud.get(me['images'])

with open('thumbnail.png', 'wb') as thumbnail:
    image_data = amigocloud.get(images['thumbnail'], raw=True)
    thumbnail.write(image_data)

游标请求

许多请求返回分页列表。例如：项目、数据集、基本图层和SQL查询。当请求返回包含四个项的字典时，可以识别它们。

from amigocloud import AmigoCloud
amigocloud = AmigoCloud(token='yourapitoken')

project_list = amigocloud.get('/me/projects')
pprint ( project_list )

将返回一个类似这样的字典（为了简洁已修改）

{
    u'count': 319,
    u'next': u'https://app.amigocloud.com/api/v1/me/projects?limit=20&offset=20&token=yourapitoken',
    u'previous': None,
    u'results': []
}

从结果中，您可以看到此端点可以迭代。为了使迭代这些列表更容易，您可以使用 get_cursor 函数。游标遍历结果，如果它达到响应的极限，它将自动请求获取下一个值。因此，您可以获取所有数据并遍历它，而不用担心分页。

projects = amigocloud.get_cursor('/me/projects')
for project in projects:
    print('Project:', project['name'])

如果您想逐个请求迭代，可以按以下方式请求

# using a project token to authenticate

datasets = amigocloud.get_cursor('datasets')

dataset1 = datasets.next()
print('Dataset1:', dataset1['name'])

# Boolean to ask if there is a next value.
# otherwise a StopIteration exception is raised.
if datasets.has_next:
    dataset2 = datasets.next()
    print('Dataset2:', dataset2['name'])

此外，您还可以请求一些额外的值，这些值包含在响应中。

dataset_rows = amigocloud.get_cursor(
    'https://www.amigocloud.com/api/v1/projects/1234/sql',
    {'query': 'select * from dataset_1'})

print('Response extra values:', dataset_rows.get('columns'))

for row in dataset_rows:
    print('Row:', row)

游标可用于项目、数据集、基本图层、SQL查询等。它还支持非可迭代的响应。对于这些情况，它只返回一个结果。

cursor = amigocloud.get_cursor('me')

for me in cursor:
    print('Me:', me)

WebSocket连接

当创建AmigoCloud对象时启动WebSocket连接，当对象销毁时关闭。您始终需要使用用户令牌进行WebSocket。

在继续阅读之前，请务必阅读 我们关于WebSocket事件的帮助页面。

要开始监听与您的用户相关的WebSocket事件（多播事件），请这样做（您必须登录才能开始监听您的事件）

amigocloud.listen_user_events()

一旦您开始监听事件，您就可以向它们添加回调。回调是每当接收到事件时都会被调用的函数。这些函数应该只有一个参数，即Python字典。

def project_created(data):
    print 'User id=%(user_id)s created project id=%(project_id)s' % data
amigocloud.add_callback('project:creation_succeeded', project_created)

实时事件是与实时数据集相关的广播事件。要开始监听它们，请执行以下操作：

amigocloud.listen_dataset_events(owner_id, project_id, dataset_id)

然后为它们添加一个回调函数

def realtime(data):
    print 'Realtime dataset id=%(dataset_id)s' % data
    for obj in data['data']:
        print "Object '%(object_id)s' is now at (%(latitude)s, %(longitude)s)" % obj
amigocloud.add_callback('realtime', realtime)

最后，开始运行WebSocket客户端

ac.start_listening()

此方法接收一个可选参数 seconds。如果 seconds 是 None（默认值），则客户端将永久监听。您可能希望在新线程中运行此方法。

异常

如果在请求过程中出现任何问题，将引发 AmigoCloudError 异常

try:
    amigocloud.post('me/projects')
except AmigoCloudError as err:
    print 'Something failed!'
    print 'Status code was', err.response.status_code
    print 'Message from server was', err.text