public class Index extends TaskClusterRequestHandler
The task index, typically available at index.taskcluster.net, is responsible for indexing tasks. In order to ensure that tasks can be located by recency and/or arbitrary strings. Common use-cases includes
<revision>, or<branch>, such as a release.Index hierarchy, tasks are indexed in a dot . separated hierarchy called a namespace. For example a task could be indexed in <revision>.linux-64.release-build. In this case the following namespaces is created.
<revision>, and,<revision>.linux-64The inside the namespace <revision> you can find the namespace <revision>.linux-64 inside which you can find the indexed task <revision>.linux-64.release-build. In this example you’ll be able to find build for a given revision.
Task Rank, when a task is indexed, it is assigned a rank (defaults to 0). If another task is already indexed in the same namespace with the same lower or equal rank, the task will be overwritten. For example consider a task indexed as mozilla-central.linux-64.release-build, in this case on might choose to use a unix timestamp or mercurial revision number as rank. This way the latest completed linux 64 bit release build is always available at mozilla-central.linux-64.release-build.
Indexed Data, when a task is located in the index you will get the taskId and an additional user-defined JSON blob that was indexed with task. You can use this to store additional information you would like to get additional from the index.
Entry Expiration, all indexed entries must have an expiration date. Typically this defaults to one year, if not specified. If you are indexing tasks to make it easy to find artifacts, consider using the expiration date that the artifacts is assigned.
Valid Characters, all keys in a namespace <key1>.<key2> must be in the form /[a-zA-Z0-9_!~*'()%-]+/. Observe that this is URL-safe and that if you strictly want to put another character you can URL encode it.
Indexing Routes, tasks can be indexed using the API below, but the most common way to index tasks is adding a custom route on the following form index.<namespace>. In-order to add this route to a task you’ll need the following scope queue:route:index.<namespace>. When a task has this route, it’ll be indexed when the task is completed successfully. The task will be indexed with rank, data and expires as specified in task.extra.index, see example below:
{
payload: { /* ... * / },
routes: [
// index.<namespace> prefixed routes, tasks CC'ed such a route will
// be indexed under the given <namespace>
"index.mozilla-central.linux-64.release-build",
"index.<revision>.linux-64.release-build"
],
extra: {
// Optional details for indexing service
index: {
// Ordering, this taskId will overwrite any thing that has
// rank <= 4000 (defaults to zero)
rank: 4000,
// Specify when the entries expires (Defaults to 1 year)
expires: new Date().toJSON(),
// A little informal data to store along with taskId
// (less 16 kb when encoded as JSON)
data: {
hgRevision: "...",
commitMessae: "...",
whatever...
}
},
// Extra properties for other services...
}
// Other task properties...
}
Remark, when indexing tasks using custom routes, it’s also possible to listen for messages about these tasks. Which is quite convenient, for example one could bind to route.index.mozilla-central.*.release-build, and pick up all messages about release builds. Hence, it is a good idea to document task index hierarchies, as these make up extension points in their own.
See: https://docs.taskcluster.net/reference/core/index/api-docs
| Modifier and Type | Field and Description |
|---|---|
protected static String |
defaultBaseURL |
| Constructor and Description |
|---|
Index() |
Index(Credentials credentials) |
Index(Credentials credentials,
String baseURL) |
Index(String baseURL) |
Index(String clientId,
String accessToken) |
Index(String clientId,
String accessToken,
String certificate) |
| Modifier and Type | Method and Description |
|---|---|
CallSummary<EmptyPayload,EmptyPayload> |
findArtifactFromTask(String namespace,
String name)
Find task by namespace and redirect to artifact with given
name, if no task existing for the given namespace, this API end-point respond 404. |
CallSummary<EmptyPayload,IndexedTaskResponse> |
findTask(String namespace)
Find task by namespace, if no task existing for the given namespace, this API end-point respond
404. |
CallSummary<InsertTaskRequest,IndexedTaskResponse> |
insertTask(String namespace,
InsertTaskRequest payload)
Insert a task into the index.
|
CallSummary<ListNamespacesRequest,ListNamespacesResponse> |
listNamespaces(String namespace,
ListNamespacesRequest payload)
List the namespaces immediately under a given namespace.
|
CallSummary<ListTasksRequest,ListTasksResponse> |
listTasks(String namespace,
ListTasksRequest payload)
List the tasks immediately under a given namespace.
|
CallSummary<EmptyPayload,EmptyPayload> |
ping()
Documented later…
|
apiCall, setBaseURL, uriEncodeprotected static final String defaultBaseURL
public Index(Credentials credentials)
public Index(Credentials credentials, String baseURL)
public Index(String baseURL)
public Index()
public CallSummary<EmptyPayload,IndexedTaskResponse> findTask(String namespace) throws APICallFailure
Find task by namespace, if no task existing for the given namespace, this API end-point respond 404.
See https://docs.taskcluster.net/reference/core/index/api-docs#findTask
APICallFailurepublic CallSummary<ListNamespacesRequest,ListNamespacesResponse> listNamespaces(String namespace, ListNamespacesRequest payload) throws APICallFailure
List the namespaces immediately under a given namespace. This end-point list up to 1000 namespaces. If more namespaces are present a continuationToken will be returned, which can be given in the next request. For the initial request, the payload should be an empty JSON object.
Remark, this end-point is designed for humans browsing for tasks, not services, as that makes little sense.
See https://docs.taskcluster.net/reference/core/index/api-docs#listNamespaces
APICallFailurepublic CallSummary<ListTasksRequest,ListTasksResponse> listTasks(String namespace, ListTasksRequest payload) throws APICallFailure
List the tasks immediately under a given namespace. This end-point list up to 1000 tasks. If more tasks are present a continuationToken will be returned, which can be given in the next request. For the initial request, the payload should be an empty JSON object.
Remark, this end-point is designed for humans browsing for tasks, not services, as that makes little sense.
See https://docs.taskcluster.net/reference/core/index/api-docs#listTasks
APICallFailurepublic CallSummary<InsertTaskRequest,IndexedTaskResponse> insertTask(String namespace, InsertTaskRequest payload) throws APICallFailure
Insert a task into the index. Please see the introduction above, for how to index successfully completed tasks automatically, using custom routes.
See https://docs.taskcluster.net/reference/core/index/api-docs#insertTask
APICallFailurepublic CallSummary<EmptyPayload,EmptyPayload> findArtifactFromTask(String namespace, String name) throws APICallFailure
Find task by namespace and redirect to artifact with given name, if no task existing for the given namespace, this API end-point respond 404.
See https://docs.taskcluster.net/reference/core/index/api-docs#findArtifactFromTask
APICallFailurepublic CallSummary<EmptyPayload,EmptyPayload> ping() throws APICallFailure
Documented later…
Warning this api end-point is not stable.
See https://docs.taskcluster.net/reference/core/index/api-docs#ping
APICallFailureCopyright © 2014–2016 Mozilla. All rights reserved.