Python FireStoreAdminClient: Cannot pass outputUriPrefix as metadata for export_documents method

[durcheinandermann]

Hi there,

I'm struggling to use the Python firestore_admin client's export_documents method as documented here: https://googleapis.dev/python/firestore/latest/admin_client.html#google.cloud.firestore_admin_v1.services.firestore_admin.client.FirestoreAdminClient.export_documents

Whenever I pass "outputUriPrefix" with a valid gs://XXXXX path as metadata, I get an error indicating that "outputUriPrefix" is an illegal header key. I suspected this to be due to uppercase letters and tried output_uri_prefix and output-uri-prefix. However, doing so results in google.api_core.exceptions.InvalidArgument: 400 Missing required field: output_uri_prefix.

I searched documentation intensively but could not find anything, thus I suspect a bug. I am sure my actual metadata value is fine as well as the name parameter of export_documents, tested via browser interface "Try this API" on https://cloud.google.com/firestore/docs/reference/rest/v1beta1/projects.databases/exportDocument.

How do I pass the outputUriPrefix metadata correctly?

Environment details

• OS type and version: Linux, Kubuntu 20.04
• Python version: Python 3.8.5
• pip version: 20.2.2
• google-cloud-firestore version: 2.0.2

Steps to reproduce

1. Set up Python Firestore admin client
2. Call client's export_document method and pass outputUriPrefix as metadata

Code example

from google.cloud import firestore_admin_v1
admin_client = firestore_admin_v1.FirestoreAdminClient()
admin_client.export_documents(
    name=f"projects/XXXXX/databases/(default)",
    metadata=[
        ("outputUriPrefix", "gs://XXXXX"),
    ],
)

Stack trace

E0211 12:07:31.475030655   18348 call.cc:919]                validate_metadata: {"created":"@1613041651.475006017","description":"Illegal header key","file":"src/core/lib/surface/validate_metadata.cc","file_line":44,"offset":6,"raw_bytes":"6f 75 74 70 75 74 55 72 69 50 72 65 66 69 78 'outputUriPrefix'\u0000"}

...

ValueError: metadata was invalid: [('outputUriPrefix', 'gs://XXXXX'), ('x-goog-request-params', 'name=projects/XXXXX/databases/%28default%29'), ('x-goog-api-client', 'gl-python/3.8.5 grpc/1.35.0 gax/1.22.1')]

[crwilcox]

We generally don't recommend using the gRPC clients directly, the documentation in the protos: https://github.com/googleapis/googleapis/blob/d76f26f335b2b570b7e19d938f35f9894236e565/google/firestore/admin/v1/firestore_admin.proto#L310

// The request for [FirestoreAdmin.ExportDocuments][google.firestore.admin.v1.FirestoreAdmin.ExportDocuments].
message ExportDocumentsRequest {
  // Required. Database to export. Should be of the form:
  // `projects/{project_id}/databases/{database_id}`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "firestore.googleapis.com/Database"
    }
  ];

  // Which collection ids to export. Unspecified means all collections.
  repeated string collection_ids = 2;

  // The output URI. Currently only supports Google Cloud Storage URIs of the
  // form: `gs://BUCKET_NAME[/NAMESPACE_PATH]`, where `BUCKET_NAME` is the name
  // of the Google Cloud Storage bucket and `NAMESPACE_PATH` is an optional
  // Google Cloud Storage namespace path. When
  // choosing a name, be sure to consider Google Cloud Storage naming
  // guidelines: https://cloud.google.com/storage/docs/naming.
  // If the URI is a bucket (without a namespace path), a prefix will be
  // generated based on the start time.
  string output_uri_prefix = 3;
}