| Index: tools/telemetry/third_party/gsutilz/gslib/addlhelp/metadata.py
|
| diff --git a/tools/telemetry/third_party/gsutilz/gslib/addlhelp/metadata.py b/tools/telemetry/third_party/gsutilz/gslib/addlhelp/metadata.py
|
| deleted file mode 100644
|
| index f0b547fd1bf441dcf0e4c48f44009dc4b6765810..0000000000000000000000000000000000000000
|
| --- a/tools/telemetry/third_party/gsutilz/gslib/addlhelp/metadata.py
|
| +++ /dev/null
|
| @@ -1,211 +0,0 @@
|
| -# -*- coding: utf-8 -*-
|
| -# Copyright 2012 Google Inc. All Rights Reserved.
|
| -#
|
| -# 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.
|
| -"""Additional help about object metadata."""
|
| -
|
| -from __future__ import absolute_import
|
| -
|
| -from gslib.help_provider import HelpProvider
|
| -
|
| -_DETAILED_HELP_TEXT = ("""
|
| -<B>OVERVIEW OF METADATA</B>
|
| - Objects can have associated metadata, which control aspects of how
|
| - GET requests are handled, including Content-Type, Cache-Control,
|
| - Content-Disposition, and Content-Encoding (discussed in more detail in
|
| - the subsections below). In addition, you can set custom metadata that
|
| - can be used by applications (e.g., tagging that particular objects possess
|
| - some property).
|
| -
|
| - There are two ways to set metadata on objects:
|
| -
|
| - - at upload time you can specify one or more headers to associate with
|
| - objects, using the gsutil -h option. For example, the following command
|
| - would cause gsutil to set the Content-Type and Cache-Control for each
|
| - of the files being uploaded:
|
| -
|
| - gsutil -h "Content-Type:text/html" \\
|
| - -h "Cache-Control:public, max-age=3600" cp -r images \\
|
| - gs://bucket/images
|
| -
|
| - Note that -h is an option on the gsutil command, not the cp sub-command.
|
| -
|
| - - You can set or remove metadata fields from already uploaded objects using
|
| - the gsutil setmeta command. See "gsutil help setmeta".
|
| -
|
| - More details about specific pieces of metadata are discussed below.
|
| -
|
| -
|
| -<B>CONTENT TYPE</B>
|
| - The most commonly set metadata is Content-Type (also known as MIME type),
|
| - which allows browsers to render the object properly.
|
| - gsutil sets the Content-Type automatically at upload time, based on each
|
| - filename extension. For example, uploading files with names ending in .txt
|
| - will set Content-Type to text/plain. If you're running gsutil on Linux or
|
| - MacOS and would prefer to have content type set based on naming plus content
|
| - examination, see the use_magicfile configuration variable in the gsutil/boto
|
| - configuration file (See also "gsutil help config"). In general, using
|
| - use_magicfile is more robust and configurable, but is not available on
|
| - Windows.
|
| -
|
| - If you specify a Content-Type header with -h when uploading content (like the
|
| - example gsutil command given in the previous section), it overrides the
|
| - Content-Type that would have been set based on filename extension or content.
|
| - This can be useful if the Content-Type detection algorithm doesn't work as
|
| - desired for some of your files.
|
| -
|
| - You can also completely suppress content type detection in gsutil, by
|
| - specifying an empty string on the Content-Type header:
|
| -
|
| - gsutil -h 'Content-Type:' cp -r images gs://bucket/images
|
| -
|
| - In this case, the Google Cloud Storage service will not attempt to detect
|
| - the content type. In general this approach will work better than using
|
| - filename extension-based content detection in gsutil, because the list of
|
| - filename extensions is kept more current in the server-side content detection
|
| - system than in the Python library upon which gsutil content type detection
|
| - depends. (For example, at the time of writing this, the filename extension
|
| - ".webp" was recognized by the server-side content detection system, but
|
| - not by gsutil.)
|
| -
|
| -
|
| -<B>CACHE-CONTROL</B>
|
| - Another commonly set piece of metadata is Cache-Control, which allows
|
| - you to control whether and for how long browser and Internet caches are
|
| - allowed to cache your objects. Cache-Control only applies to objects with
|
| - a public-read ACL. Non-public data are not cacheable.
|
| -
|
| - Here's an example of uploading an object set to allow caching:
|
| -
|
| - gsutil -h "Cache-Control:public,max-age=3600" cp -a public-read \\
|
| - -r html gs://bucket/html
|
| -
|
| - This command would upload all files in the html directory (and subdirectories)
|
| - and make them publicly readable and cacheable, with cache expiration of
|
| - one hour.
|
| -
|
| - Note that if you allow caching, at download time you may see older versions
|
| - of objects after uploading a newer replacement object. Note also that because
|
| - objects can be cached at various places on the Internet there is no way to
|
| - force a cached object to expire globally (unlike the way you can force your
|
| - browser to refresh its cache).
|
| -
|
| - Another use of the Cache-Control header is through the "no-transform" value,
|
| - which instructs Google Cloud Storage to not apply any content transformations
|
| - based on specifics of a download request, such as removing gzip
|
| - content-encoding for incompatible clients. Note that this parameter is only
|
| - respected by the XML API. The Google Cloud Storage JSON API respects only the
|
| - no-cache and max-age Cache-Control parameters.
|
| -
|
| - Note that if you upload an object with a public-read ACL and don't include a
|
| - Cache-Control header, it will be served with a Cache-Control header allowing
|
| - the object to be cached for 3600 seconds. This will not happen if the object
|
| - is uploaded with a non-public ACL and then changed to public. Moreover, if you
|
| - upload an object with a public-read ACL and later change the ACL not to be
|
| - public-read, the object will no longer be served with the default
|
| - Cache-Control header noted above (so will be served as not cacheable).
|
| -
|
| - For details about how to set the Cache-Control header see
|
| - "gsutil help setmeta".
|
| -
|
| -
|
| -<B>CONTENT-ENCODING</B>
|
| - You can specify a Content-Encoding to indicate that an object is compressed
|
| - (for example, with gzip compression) while maintaining its Content-Type.
|
| - You will need to ensure that the files have been compressed using the
|
| - specified Content-Encoding before using gsutil to upload them. Consider the
|
| - following example for Linux:
|
| -
|
| - echo "Highly compressible text" | gzip > foo.txt
|
| - gsutil -h "Content-Encoding:gzip" -h "Content-Type:text/plain" \\
|
| - cp foo.txt gs://bucket/compressed
|
| -
|
| - Note that this is different from uploading a gzipped object foo.txt.gz with
|
| - Content-Type: application/x-gzip because most browsers are able to
|
| - dynamically decompress and process objects served with Content-Encoding: gzip
|
| - based on the underlying Content-Type.
|
| -
|
| - For compressible content, using Content-Encoding: gzip saves network and
|
| - storage costs, and improves content serving performance. However, for content
|
| - that is already inherently compressed (archives and many media formats, for
|
| - instance) applying another level of compression via Content-Encoding is
|
| - typically detrimental to both object size and performance and should be
|
| - avoided.
|
| -
|
| - Note also that gsutil provides an easy way to cause content to be compressed
|
| - and stored with Content-Encoding: gzip: see the -z option in "gsutil help cp".
|
| -
|
| -
|
| -<B>CONTENT-DISPOSITION</B>
|
| - You can set Content-Disposition on your objects, to specify presentation
|
| - information about the data being transmitted. Here's an example:
|
| -
|
| - gsutil -h 'Content-Disposition:attachment; filename=filename.ext' \\
|
| - cp -r attachments gs://bucket/attachments
|
| -
|
| - Setting the Content-Disposition allows you to control presentation style
|
| - of the content, for example determining whether an attachment should be
|
| - automatically displayed vs should require some form of action from the user to
|
| - open it. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec19.html#sec19.5.1
|
| - for more details about the meaning of Content-Disposition.
|
| -
|
| -
|
| -<B>CUSTOM METADATA</B>
|
| - You can add your own custom metadata (e.g,. for use by your application)
|
| - to an object by setting a header that starts with "x-goog-meta", for example:
|
| -
|
| - gsutil -h x-goog-meta-reviewer:jane cp mycode.java gs://bucket/reviews
|
| -
|
| - You can add multiple differently named custom metadata fields to each object.
|
| -
|
| -
|
| -<B>SETTABLE FIELDS; FIELD VALUES</B>
|
| - You can't set some metadata fields, such as ETag and Content-Length. The
|
| - fields you can set are:
|
| -
|
| - - Cache-Control
|
| - - Content-Disposition
|
| - - Content-Encoding
|
| - - Content-Language
|
| - - Content-MD5
|
| - - Content-Type
|
| - - Any field starting with a matching Cloud Storage Provider
|
| - prefix, such as x-goog-meta- (i.e., custom metadata).
|
| -
|
| - Header names are case-insensitive.
|
| -
|
| - x-goog-meta- fields can have data set to arbitrary Unicode values. All
|
| - other fields must have ASCII values.
|
| -
|
| -
|
| -<B>VIEWING CURRENTLY SET METADATA</B>
|
| - You can see what metadata is currently set on an object by using:
|
| -
|
| - gsutil ls -L gs://the_bucket/the_object
|
| -""")
|
| -
|
| -
|
| -class CommandOptions(HelpProvider):
|
| - """Additional help about object metadata."""
|
| -
|
| - # Help specification. See help_provider.py for documentation.
|
| - help_spec = HelpProvider.HelpSpec(
|
| - help_name='metadata',
|
| - help_name_aliases=[
|
| - 'cache-control', 'caching', 'content type', 'mime type', 'mime',
|
| - 'type'],
|
| - help_type='additional_help',
|
| - help_one_line_summary='Working With Object Metadata',
|
| - help_text=_DETAILED_HELP_TEXT,
|
| - subcommand_help_text={},
|
| - )
|
|
|