diff --git a/samples/snippets/README.md b/samples/snippets/README.md new file mode 100644 index 00000000..012c56ef --- /dev/null +++ b/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. diff --git a/samples/snippets/pull_queue_snippets.py b/samples/snippets/pull_queue_snippets.py new file mode 100644 index 00000000..8d898a58 --- /dev/null +++ b/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) diff --git a/samples/snippets/pull_queue_snippets_test.py b/samples/snippets/pull_queue_snippets_test.py new file mode 100644 index 00000000..6905fdb3 --- /dev/null +++ b/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) diff --git a/samples/snippets/queue.yaml b/samples/snippets/queue.yaml new file mode 100644 index 00000000..08c1503b --- /dev/null +++ b/samples/snippets/queue.yaml @@ -0,0 +1,3 @@ +queue: +- name: my-pull-queue + mode: pull diff --git a/samples/snippets/requirements.txt b/samples/snippets/requirements.txt new file mode 100644 index 00000000..b7233cdf --- /dev/null +++ b/samples/snippets/requirements.txt @@ -0,0 +1 @@ +google-api-python-client==1.6.0