FR: Support direct lookup of Storage objects by `metadata.id`

[Programmer-RD-AI]

Title:
FR: Support direct lookup of Storage objects by metadata.id

---

Is your feature request related to a problem? Please describe.
Currently in the Admin SDK there is no way to fetch a file reference directly by its internal metadata.id. Users must call bucket.getFiles() (optionally with a prefix) and then iterate through every file’s metadata until they find a match. This approach is painfully inefficient for buckets with hundreds or thousands of objects, and leads to high latency and extra egress charges just to resolve a single file by its ID.

---

Describe the solution you’d like
Add a first-class API—e.g.

const file = await bucket.fileById('ABCD1234-xyz');

under the Admin SDK’s Bucket class (and optionally in the underlying @google-cloud/storage client). Internally it could leverage a server-side lookup or index rather than requiring a full listing scan. The returned object should behave identically to bucket.file(path) so you can immediately call getMetadata(), download(), or getSignedUrl().

---

Describe alternatives you’ve considered

• Client-side scan:

  const [files] = await bucket.getFiles();
  for (const f of files) {
    const [m] = await f.getMetadata();
    if (m.id === targetId) return f;
  }

Works, but requires listing every object + extra round-trips.

• Storing custom metadata: You could save your own “id” in metadata.custom and index it in Firestore, but that duplicates what the server already knows, and still needs a separate database lookup.

---

Additional context

• This feature is especially important for multi-tenant or large-scale apps where buckets routinely hit thousands of files.
• Without it, reverse-lookup patterns become a maintenance burden and performance bottleneck.
• Screenshot of current workaround and templates attached.