1# -*- coding: utf-8 -*- 2# Copyright 2014 Google Inc. All Rights Reserved. 3# 4# Licensed under the Apache License, Version 2.0 (the "License"); 5# you may not use this file except in compliance with the License. 6# You may obtain a copy of the License at 7# 8# http://www.apache.org/licenses/LICENSE-2.0 9# 10# Unless required by applicable law or agreed to in writing, software 11# distributed under the License is distributed on an "AS IS" BASIS, 12# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13# See the License for the specific language governing permissions and 14# limitations under the License. 15"""Additional help about gsutil's interaction with Cloud Storage APIs.""" 16 17from gslib.help_provider import HelpProvider 18 19_DETAILED_HELP_TEXT = (""" 20<B>OVERVIEW</B> 21 Google Cloud Storage offers two APIs: an XML and a JSON API. Gsutil can 22 interact with both APIs. By default, gsutil versions starting with 4.0 23 interact with the JSON API. If it is not possible to perform a command using 24 one of the APIs (for example, the notification command is not supported in 25 the XML API), gsutil will silently fall back to using the other API. Also, 26 gsutil will automatically fall back to using the XML API when interacting 27 with cloud storage providers that only support that API. 28 29<B>CONFIGURING WHICH API IS USED</B> 30 To use a certain API for interacting with Google Cloud Storage, you can set 31 the 'prefer_api' variable in the "GSUtil" section of .boto config file to 32 'xml' or 'json' like so: 33 34 prefer_api = json 35 36 This will cause gsutil to use that API where possible (falling back to the 37 other API in cases as noted above). This applies to the gsutil test command 38 as well; it will run integration tests against the preferred API. 39 40<B>PERFORMANCE AND COST DIFFERENCES BETWEEN APIS</B> 41 The XML API uses the boto framework. This framework re-reads downloaded files 42 to compute an MD5 hash if one is not present. For objects that do not 43 include MD5 hashes in their metadata (for example Google Cloud Storage 44 composite objects), this doubles the bandwidth consumed and elapsed time 45 needed by the download. Therefore, if you are working with composite objects, 46 it is recommended that you use the default value for prefer_api. 47 48 The XML API also requires separate calls to get different object and bucket 49 metadata fields, such as ACLs or bucket configuration. Thus, using the JSON 50 API when possible uses fewer operations (and thus has a lower cost). 51""") 52 53 54class CommandOptions(HelpProvider): 55 """Additional help about gsutil's interaction with Cloud Storage APIs.""" 56 57 # Help specification. See help_provider.py for documentation. 58 help_spec = HelpProvider.HelpSpec( 59 help_name='apis', 60 help_name_aliases=['XML', 'JSON', 'api', 'force_api', 'prefer_api'], 61 help_type='additional_help', 62 help_one_line_summary='Cloud Storage APIs', 63 help_text=_DETAILED_HELP_TEXT, 64 subcommand_help_text={}, 65 ) 66 67