Add samples for Cloud Tasks [(#1068)](GoogleCloudPlatform/python-docs…

…-samples#1068)

* Add samples for Cloud Tasks

* Respond to tasks sample review

* Update app engine queues samples

* Address review feedback

* Address review issues and convert pull queue sample to not use API key auth

* Reform pull queues to match appengine queues changes to auth, command line input, readme

* flake8 and fix comment

samples/snippets/README.md

@@ -0,0 +1,59 @@
+# Google Cloud Tasks Pull Queue Samples
+
+Sample command-line program for interacting with the Google Cloud Tasks API
+using pull queues.
+
+Pull queues let you add tasks to a queue, then programatically remove and
+interact with them. Tasks can be added or processed in any environment,
+such as on Google App Engine or Google Compute Engine.
+
+`pull_queue_snippets.py` is a simple command-line program to demonstrate listing queues,
+ creating tasks, and pulling and acknowledging tasks.
+
+## Prerequisites to run locally:
+
+Please refer to [Setting Up a Python Development Environment](https://cloud.google.com/python/setup).
+
+## Authentication
+
+To set up authentication, please refer to our
+[authentication getting started guide](https://cloud.google.com/docs/authentication/getting-started).
+
+## Creating a queue
+
+To create a queue using the Cloud SDK, use the following gcloud command:
+
+    gcloud alpha tasks queues create-pull-queue my-pull-queue
+
+## Running the Samples
+
+Set the environment variables:
+
+Set environment variables:
+
+First, your project ID:
+
+    export PROJECT_ID=my-project-id
+
+Then the queue ID, as specified at queue creation time. Queue IDs already
+created can be listed with `gcloud alpha tasks queues list`.
+
+    export QUEUE_ID=my-pull-queue
+
+And finally the location ID, which can be discovered with
+`gcloud alpha tasks queues describe $QUEUE_ID`, with the location embedded in
+the "name" value (for instance, if the name is
+"projects/my-project/locations/us-central1/queues/my-pull-queue", then the
+location is "us-central1").
+
+    export LOCATION_ID=us-central1
+
+Create a task for a queue:
+
+    python pull_queue_snippets.py create-task --project=$PROJECT_ID --queue=$QUEUE_ID --location=$LOCATION_ID
+
+Pull and acknowledge a task:
+
+    python pull_queue_snippets.py pull-and-ack-task --project=$PROJECT_ID --queue=$QUEUE_ID --location=$LOCATION_ID
+
+Note that usually, there would be a processing step in between pulling a task and acknowledging it.

samples/snippets/pull_queue_snippets.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python
+
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+"""Sample command-line program for interacting with the Cloud Tasks API.
+
+See README.md for instructions on setting up your development environment
+and running the scripts.
+"""
+
+import argparse
+import base64
+
+from googleapiclient import discovery
+
+
+def create_task(project, queue, location):
+    """Create a task for a given queue with an arbitrary payload."""
+
+    DISCOVERY_URL = (
+        'https://cloudtasks.googleapis.com/$discovery/rest?version=v2beta2')
+    client = discovery.build(
+        'cloudtasks', 'v2beta2', discoveryServiceUrl=DISCOVERY_URL)
+
+    payload = 'a message for the recipient'
+    task = {
+        'task': {
+            'pull_task_target': {
+                'payload': base64.b64encode(payload)
+            }
+        }
+    }
+
+    queue_name = 'projects/{}/locations/{}/queues/{}'.format(
+        project, location, queue)
+
+    response = client.projects().locations().queues().tasks().create(
+        parent=queue_name, body=task).execute()
+
+    print('Created task {}'.format(response['name']))
+    return response
+
+
+def pull_task(project, queue, location):
+    """Pull a single task from a given queue and lease it for 10 minutes."""
+
+    DISCOVERY_URL = (
+        'https://cloudtasks.googleapis.com/$discovery/rest?version=v2beta2')
+    client = discovery.build(
+        'cloudtasks', 'v2beta2', discoveryServiceUrl=DISCOVERY_URL)
+
+    duration_seconds = '600s'
+    pull_options = {
+        'max_tasks': 1,
+        'leaseDuration': duration_seconds,
+        'responseView': 'FULL'
+    }
+
+    queue_name = 'projects/{}/locations/{}/queues/{}'.format(
+        project, location, queue)
+
+    response = client.projects().locations().queues().tasks().pull(
+        name=queue_name, body=pull_options).execute()
+
+    print('Pulled task {}'.format(response))
+    return response['tasks'][0]
+
+
+def acknowledge_task(task):
+    """Acknowledge a given task."""
+
+    DISCOVERY_URL = (
+        'https://cloudtasks.googleapis.com/$discovery/rest?version=v2beta2')
+    client = discovery.build(
+        'cloudtasks', 'v2beta2', discoveryServiceUrl=DISCOVERY_URL)
+
+    body = {'scheduleTime': task['scheduleTime']}
+    client.projects().locations().queues().tasks().acknowledge(
+        name=task['name'], body=body).execute()
+
+    print('Acknowledged task {}'.format(task['name']))
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+
+    subparsers = parser.add_subparsers(dest='command')
+
+    create_task_parser = subparsers.add_parser(
+        'create-task',
+        help=create_task.__doc__)
+    create_task_parser.add_argument(
+        '--project',
+        help='Project of the queue to add the task to.'
+    )
+    create_task_parser.add_argument(
+        '--queue',
+        help='ID (short name) of the queue to add the task to.'
+    )
+    create_task_parser.add_argument(
+        '--location',
+        help='Location of the queue to add the task to.'
+    )
+
+    pull_and_ack_parser = subparsers.add_parser(
+        'pull-and-ack-task',
+        help=create_task.__doc__)
+    pull_and_ack_parser.add_argument(
+        '--project',
+        help='Project of the queue to pull the task from.'
+    )
+    pull_and_ack_parser.add_argument(
+        '--queue',
+        help='ID (short name) of the queue to pull the task from.'
+    )
+    pull_and_ack_parser.add_argument(
+        '--location',
+        help='Location of the queue to pull the task from.'
+    )
+
+    args = parser.parse_args()
+
+    if args.command == 'create-task':
+        create_task(args.project, args.queue, args.location)
+    if args.command == 'pull-and-ack-task':
+        task = pull_task(args.project, args.queue, args.location)
+        acknowledge_task(task)

samples/snippets/pull_queue_snippets_test.py

@@ -0,0 +1,35 @@
+# Copyright 2017 Google Inc.
+#
+# 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.
+
+import os
+
+import pull_queue_snippets
+
+TEST_PROJECT_ID = os.getenv('GCLOUD_PROJECT')
+TEST_LOCATION = os.getenv('TEST_QUEUE_LOCATION', 'us-central1')
+TEST_QUEUE_NAME = os.getenv('TEST_QUEUE_NAME', 'test-queue')
+
+
+def test_create_task():
+    result = pull_queue_snippets.create_task(
+        TEST_PROJECT_ID, TEST_QUEUE_NAME, TEST_LOCATION)
+    assert TEST_QUEUE_NAME in result['name']
+
+
+def test_pull_and_ack_task():
+    pull_queue_snippets.create_task(
+        TEST_PROJECT_ID, TEST_QUEUE_NAME, TEST_LOCATION)
+    task = pull_queue_snippets.pull_task(
+        TEST_PROJECT_ID, TEST_QUEUE_NAME, TEST_LOCATION)
+    pull_queue_snippets.acknowledge_task(task)

samples/snippets/queue.yaml

@@ -0,0 +1,3 @@
+queue:
+- name: my-pull-queue
+  mode: pull

samples/snippets/requirements.txt

@@ -0,0 +1 @@
+google-api-python-client==1.6.0