151 lines
4.7 KiB
ReStructuredText
151 lines
4.7 KiB
ReStructuredText
..
|
|
Copyright 2017 AT&T Intellectual Property.
|
|
All Rights Reserved.
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
|
not use this file except in compliance with the License. You may obtain
|
|
a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
|
License for the specific language governing permissions and limitations
|
|
under the License.
|
|
|
|
.. _api-client-library:
|
|
|
|
Deckhand API Client Library Documentation
|
|
=========================================
|
|
|
|
The recommended approach to instantiate the Deckhand client is via a Keystone
|
|
session:
|
|
|
|
::
|
|
|
|
from keystoneauth1.identity import v3
|
|
from keystoneauth1 import session
|
|
|
|
keystone_auth = {
|
|
'project_domain_name': PROJECT_DOMAIN_NAME,
|
|
'project_name': PROJECT_NAME,
|
|
'user_domain_name': USER_DOMAIN_NAME,
|
|
'password': PASSWORD,
|
|
'username': USERNAME,
|
|
'auth_url': AUTH_URL,
|
|
}
|
|
auth = v3.Password(**keystone_auth)
|
|
sess = session.Session(auth=auth)
|
|
deckhandclient = client.Client(session=sess)
|
|
|
|
You can also instantiate the client via one of Keystone's supported ``auth``
|
|
plugins:
|
|
|
|
::
|
|
|
|
from keystoneauth1.identity import v3
|
|
|
|
keystone_auth = {
|
|
'auth_url': AUTH_URL,
|
|
'token': TOKEN,
|
|
'project_id': PROJECT_ID,
|
|
'project_domain_name': PROJECT_DOMAIN_NAME
|
|
}
|
|
auth = v3.Token(**keystone_auth)
|
|
deckhandclient = client.Client(auth=auth)
|
|
|
|
Which will allow you to authenticate using a pre-existing, project-scoped
|
|
token.
|
|
|
|
Alternatively, you can use non-session authentication to instantiate the
|
|
client, though this approach has been `deprecated`_.
|
|
|
|
::
|
|
|
|
from deckhand.client import client
|
|
|
|
deckhandclient = client.Client(
|
|
username=USERNAME,
|
|
password=PASSWORD,
|
|
project_name=PROECT_NAME,
|
|
project_domain_name=PROJECT_DOMAIN_NAME,
|
|
user_domain_name=USER_DOMAIN_NAME,
|
|
auth_url=AUTH_URL)
|
|
|
|
.. _deprecated: https://docs.openstack.org/python-keystoneclient/latest/using-api-v3.html#non-session-authentication-deprecated
|
|
|
|
.. note::
|
|
|
|
The Deckhand client by default expects that the service be registered
|
|
under the Keystone service catalog as ``deckhand``. To provide a different
|
|
value pass ``service_type=SERVICE_TYPE`` to the ``Client`` constructor.
|
|
|
|
After you have instantiated an instance of the Deckhand client, you can invoke
|
|
the client managers' functionality:
|
|
|
|
::
|
|
|
|
# Generate a sample document.
|
|
payload = """
|
|
---
|
|
schema: deckhand/Certificate/v1
|
|
metadata:
|
|
schema: metadata/Document/v1
|
|
name: application-api
|
|
storagePolicy: cleartext
|
|
data: |-
|
|
-----BEGIN CERTIFICATE-----
|
|
MIIDYDCCAkigAwIBAgIUKG41PW4VtiphzASAMY4/3hL8OtAwDQYJKoZIhvcNAQEL
|
|
...snip...
|
|
P3WT9CfFARnsw2nKjnglQcwKkKLYip0WY2wh3FE7nrQZP6xKNaSRlh6p2pCGwwwH
|
|
HkvVwA==
|
|
-----END CERTIFICATE-----
|
|
"""
|
|
|
|
# Create a bucket and associate it with the document.
|
|
result = client.buckets.update('mop', payload)
|
|
|
|
>>> result
|
|
<Bucket name: mop>
|
|
|
|
# Convert the response to a dictionary.
|
|
>>> result.to_dict()
|
|
{'status': {'bucket': 'mop', 'revision': 1},
|
|
'schema': 'deckhand/Certificate/v1', 'data': {...} 'id': 1,
|
|
'metadata': {'layeringDefinition': {'abstract': False},
|
|
'storagePolicy': 'cleartext', 'name': 'application-api',
|
|
'schema': 'metadata/Document/v1'}}
|
|
|
|
# Show the revision that was created.
|
|
revision = client.revisions.get(1)
|
|
|
|
>>> revision.to_dict()
|
|
{'status': 'success', 'tags': {},
|
|
'url': 'https://deckhand/api/v1.0/revisions/1',
|
|
'buckets': ['mop'], 'validationPolicies': [], 'id': 1,
|
|
'createdAt': '2017-12-09T00:15:04.309071'}
|
|
|
|
# List all revisions.
|
|
revisions = client.revisions.list()
|
|
|
|
>>> revisions.to_dict()
|
|
{'count': 1, 'results': [{'buckets': ['mop'], 'id': 1,
|
|
'createdAt': '2017-12-09T00:29:34.031460', 'tags': []}]}
|
|
|
|
# List raw documents for the created revision.
|
|
raw_documents = client.revisions.documents(1, rendered=False)
|
|
|
|
>>> [r.to_dict() for r in raw_documents]
|
|
[{'status': {'bucket': 'foo', 'revision': 1},
|
|
'schema': 'deckhand/Certificate/v1', 'data': {...}, 'id': 1,
|
|
'metadata': {'layeringDefinition': {'abstract': False},
|
|
'storagePolicy': 'cleartext', 'name': 'application-api',
|
|
'schema': 'metadata/Document/v1'}}]
|
|
|
|
Client Reference
|
|
----------------
|
|
|
|
For more information about how to use the Deckhand client, refer to the
|
|
`client module <../contributor/api/deckhand.client.html>`_.
|