[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-09-04。"],[],[],null,["# Use Queue Management or queue.yaml\n\nThis page explains the differences between using the\n[Cloud Tasks API](/tasks/docs/creating-queues) to manage queues\nand using the upload of a Cloud Tasks\n[`queue.yaml`](/appengine/docs/standard/reference/queueref)\nfile to accomplish the same ends. It also discusses some of the\npitfalls of mixing mechanisms and how to deal with common problems.\n\nIntroduction\n------------\n\nThe Cloud Tasks API provides an App Engine-independent interface to\nthe [App Engine Task Queue](/appengine/docs/standard/services/taskqueue)\nservice. As part of that interface, it provides the ability to manage queues,\nincluding doing so through the console or the`gcloud` command. Queues that are\ncreated by Cloud Tasks API are accessible from the App Engine SDK and vice\nversa. To maintain compatibility, it is possible to use the configuration\nfile used by the App Engine SDK, `queue.yaml`, to also create and configure\nqueues to be used through the Cloud Tasks API. However, mixing configuration\nvia file with configuration through the Cloud Tasks API can produce unexpected consequences.\n\nPitfalls of mixing `queue.yaml` with Cloud Tasks queue management methods\n-------------------------------------------------------------------------\n\nFor the underlying service,`queue.yaml` files are definitive. Uploading a `queue.yaml` that omits existing queues in your project, no matter how they were created, causes those queues to be *disabled* , or [paused](/appengine/docs/standard/services/taskqueue/push/deleting-tasks-and-queues#pausing_queues). Thus if you use the Cloud Tasks API to call `CreateQueue` or `UpdateQueue` and then upload a `queue.yaml` file that omits them, the queues that were created in the Cloud Tasks calls are disabled.\n\nConsider the following scenario:\n\n1. Call `CreateQueue` to create a queue named \"cloud-tasks-queue\".\n2. Upload a `queue.yaml` file with the following contents:\n\n queue:\n - name: queue-yaml-queue\n\nWhat is the current state of queues in this project? The queue named\n\"cloud-tasks-queue\" and any other queues that existed prior are in\n`DISABLED` state, and the queue named \"queue-yaml-queue\" is in `RUNNING`\nstate.\n| **Note:** The `default` queue is an exception. It is never disabled by App Engine. See [Cloud Tasks and the `default` App Engine queue](#cloud_tasks_and_the_default_app_engine_queue) for more details.\n\nThis behavior might be surprising if you create\nqueues through the Cloud Tasks API. The instructions below explain how to\n[resume a disabled queue](#resume-queue).\n\nSimilarly, if a queue is disabled in the Cloud Tasks API but later appears in an\nuploaded `queue.yaml` file, that queue is resumed.\n\nIf a queue is deleted with the `DeleteQueue` method and later appears in a\n`queue.yaml` file, the `queue.yaml` upload can fail because queue names are not\nallowed to be reused for several days after deletion.\n\nBest practices\n--------------\n\n| **Caution:** It is strongly recommended that you use **either** the configuration file method **or** the Cloud Tasks API to configure your queues, but not both.\n\nIf you are new to Cloud Tasks or App Engine, use the Cloud Tasks API\nexclusively to manage your queues and avoid the use of `queue.yaml`\naltogether. Cloud Tasks queue management methods give users more choice in creating, updating, and deleting queues.\n\nIf, however, you are an existing `queue.yaml` user, you should only consider switching to queue management methods if you understand the\n[pitfalls of mixing `queue.yaml` with Cloud Tasks queue management methods](#pitfalls).\n\nTo prevent users from mixing task management methods, one option is to\ncreate a web app or command line tool that all users must use to create, update,\nand delete queues. Whether that tool uses Cloud Tasks queue\nmanagement methods or `queue.yaml` is an implementation detail of the tool\nthat users do not need to worry about. If users are required to use the tool,\nthen you can guarantee that there is no inadvertent mixing of\nCloud Tasks queue management methods and `queue.yaml` use.\nTo help enforce use of such a tool, you can grant queue admin roles to the tool\nand require users to authenticate to use the tool. To learn more about access\nmanagement, see\n[Secure queue configuration](/tasks/docs/secure-queue-configuration).\n\nDebugging\n---------\n\nYou can inspect your project's\n[Admin Activity audit logs](/logging/docs/audit#viewing_audit_logs) to retrieve\nthe history of queue configuration changes including queue\ncreations, updates, and deletions: \n\n gcloud logging read \\\n 'protoPayload.methodName=\n (com.google.appengine.legacy.queue_created OR\n com.google.appengine.legacy.queue_updated OR\n google.cloud.tasks.v2.CloudTasks.CreateQueue OR\n google.cloud.tasks.v2.CloudTasks.UpdateQueue OR\n google.cloud.tasks.v2.CloudTasks.DeleteQueue)'\n\nFor example, if an existing queue is disabled by a `queue.yaml` upload, a\n\"Disabled queue '\\[QUEUE_NAME\\]'\" message would appear in the audit log through\nthe `com.google.appengine.legacy.queue_updated` method.\n\nHow to resume a queue disabled by a `queue.yaml` upload\n-------------------------------------------------------\n\nIf you\n[mix `queue.yaml` with Cloud Tasks queue management methods](#pitfalls),\nuploading a `queue.yaml` file might accidentally disable a queue created through the Cloud Tasks API.\n\nTo resume the queue, you can either call `ResumeQueue` on the queue or add it\nto `queue.yaml` and upload. Be aware that if you had previously set a custom\nprocessing\n[`rate`](/appengine/docs/standard/reference/queueref#rate)\nin the `queue.yaml` configuration for the queue,\n`ResumeQueue` resets the queue to the default `rate`. This is reflected in the\n[`maxDispatchesPerSecond`](/tasks/docs/reference/rest/v2/projects.locations.queues#RateLimits.FIELDS.max_dispatches_per_second)\nfield of the response to `ResumeQueue`.\n| **Warning:** Resuming many high-QPS queues at the same time can lead to target overloading. If you are resuming high-QPS queues, follow the 500/50/5 pattern described in [Manage scaling risks](/tasks/docs/manage-cloud-task-scaling).\n\nQuotas\n------\n\nIf you use `queue.yaml` to create your queues, by default you can create a maximum of 100 queues. Queues created\nusing the Cloud Tasks API have a default maximum of 1,000 queues. As in\nother cases, mixing `queue.yaml` and Cloud Tasks API methods can produce unexpected\nresults. For example, suppose you create some queues using `queue.yaml`, and then get a\nquota increase to, for example, 2,000. If you then subsequently use the Cloud Tasks API\nmethod of creating further queues, you will get out of quota errors. To remedy this,\nfile a request using **Edit Quotas** from the Quotas page of\nthe [Google Cloud console](https://console.cloud.google.com/iam-admin/quotas).\n\nAdditional information about Cloud Tasks queue management methods\n-----------------------------------------------------------------\n\n### Queue configuration and queue startup delay\n\nChanges to queue configuration can require several minutes to take effect. For\nexample, after calling `CreateQueue` or `UpdateQueue`, several minutes might\npass before you can successfully call `CreateTask` on that queue.\n\n### Cloud Tasks and the `default` App Engine queue\n\nThe App Engine queue named \"default\" is given special treatment in the\nApp Engine SDK and in the Cloud Tasks API.\n\nIf the `default` queue does not already exist, it is created in the following\nsituations:\n\n1. When a task is first added to the `default` queue **using the App Engine SDK**.\n2. When a `queue.yaml` file that specifies a `default` queue is uploaded.\n3. When `CreateQueue` or `UpdateQueue` is called to create the `default` queue.\n\nTo preserve compatibility with App Engine, Cloud Tasks enforces the following\nrestrictions:\n\n1. If a queue named \"default\" is created, it must be a queue using App Engine tasks.\n2. Once created, users **cannot** delete the `default` queue.\n\nIn the **Cloud Tasks API** , the following also applies to the `default` queue:\n\n1. The Cloud Tasks API does **not** automatically create the `default` queue or any other queues.\n2. Just like any other queue, calling `GetQueue` on the `default` queue results in a not found error if the call is made before the queue is created.\n3. Similarly, the `default` queue does not appear in the output of `ListQueues` before it is created.\n4. The configuration of the `default` queue can be changed with the `UpdateQueue` call.\n\nWhat's next\n-----------\n\n- See the methods available in the [RPC Cloud Tasks API](/tasks/docs/reference/rpc) in the reference documents.\n- See the methods available in the [REST Cloud Tasks API](/tasks/docs/reference/rest) in the reference documents.\n- Read about [`queue.yaml`](/appengine/docs/standard/reference/queueref)."]]
