[AIRFLOW-XXX] Add How-To-Guide to GoogleCloudStorageToSFTPOperator (#6488)

* [AIRFLOW-XXX] Add How-To-Guide to GoogleCloudStorageToSFTPOperator

airflow/example_dags/example_gcs_to_sftp.py

@@ -17,7 +17,7 @@
 # specific language governing permissions and limitations
 # under the License.
 """
-Example Airflow DAG for Google Cloud Storage to Google Cloud Storage transfer operators.
+Example Airflow DAG for Google Cloud Storage to SFTP transfer operators.
 """
 
 import os
@@ -39,13 +39,16 @@ DESTINATION_PATH_2 = "/tmp/dirs/"
 with models.DAG(
     "example_gcs_to_sftp", default_args=default_args, schedule_interval=None
 ) as dag:
+    # [START howto_operator_gcs_to_sftp_copy_single_file]
     copy_file_from_gcs_to_sftp = GoogleCloudStorageToSFTPOperator(
         task_id="file-copy-gsc-to-sftp",
         source_bucket=BUCKET_SRC,
         source_object=OBJECT_SRC_1,
         destination_path=DESTINATION_PATH_1,
     )
+    # [END howto_operator_gcs_to_sftp_copy_single_file]
 
+    # [START howto_operator_gcs_to_sftp_move_single_file_destination]
     move_file_from_gcs_to_sftp = GoogleCloudStorageToSFTPOperator(
         task_id="file-move-gsc-to-sftp",
         source_bucket=BUCKET_SRC,
@@ -53,17 +56,22 @@ with models.DAG(
         destination_path=DESTINATION_PATH_1,
         move_object=True,
     )
+    # [END howto_operator_gcs_to_sftp_move_single_file_destination]
 
+    # [START howto_operator_gcs_to_sftp_copy_directory]
     copy_dir_from_gcs_to_sftp = GoogleCloudStorageToSFTPOperator(
         task_id="dir-copy-gsc-to-sftp",
         source_bucket=BUCKET_SRC,
         source_object=OBJECT_SRC_3,
         destination_path=DESTINATION_PATH_2,
     )
+    # [END howto_operator_gcs_to_sftp_copy_directory]
 
+    # [START howto_operator_gcs_to_sftp_move_specific_files]
     move_dir_from_gcs_to_sftp = GoogleCloudStorageToSFTPOperator(
         task_id="dir-move-gsc-to-sftp",
         source_bucket=BUCKET_SRC,
         source_object=OBJECT_SRC_3,
         destination_path=DESTINATION_PATH_2,
     )
+    # [END howto_operator_gcs_to_sftp_move_specific_files]

airflow/operators/gcs_to_sftp.py

@@ -36,6 +36,10 @@ class GoogleCloudStorageToSFTPOperator(BaseOperator):
     """
     Transfer files from a Google Cloud Storage bucket to SFTP server.
 
+    .. seealso::
+        For more information on how to use this operator, take a look at the guide:
+        :ref:`howto/operator:GoogleCloudStorageToSFTPOperator`
+
     :param source_bucket: The source Google cloud storage bucket where the
          object is. (templated)
     :type source_bucket: str

docs/howto/operator/gcp/gcs_to_sftp.rst

@@ -0,0 +1,104 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you 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.
+
+
+Google Cloud Storage Transfer Operator to SFTP
+==============================================
+
+Google has a service `Google Cloud Storage <https://cloud.google.com/storage/>`__.
+This service is used to store large data from various applications.
+SFTP (SSH File Transfer Protocol) is a secure file transfer protocol.
+It runs over the SSH protocol. It supports the full security and authentication functionality of SSH.
+
+
+.. contents::
+  :depth: 1
+  :local:
+
+Prerequisite Tasks
+^^^^^^^^^^^^^^^^^^
+
+.. include:: _partials/prerequisite_tasks.rst
+
+.. _howto/operator:GoogleCloudStorageToSFTPOperator:
+
+
+Operator
+^^^^^^^^
+
+Transfer files between SFTP and Google Storage is performed with the
+:class:`~airflow.operators.gcs_to_sftp.GoogleCloudStorageToSFTPOperator` operator.
+
+Use :ref:`Jinja templating <jinja-templating>` with
+:template-fields:`airflow.operators.gcs_to_sftp.GoogleCloudStorageToSFTPOperator`
+to define values dynamically.
+
+
+Copying a single file
+---------------------
+
+The following Operator copies a single file.
+
+.. exampleinclude:: ../../../../airflow/example_dags/example_gcs_to_sftp.py
+    :language: python
+    :dedent: 4
+    :start-after: [START howto_operator_gcs_to_sftp_copy_single_file]
+    :end-before: [END howto_operator_gcs_to_sftp_copy_single_file]
+
+Moving a single file
+--------------------
+
+To move the file use the ``move_object`` parameter. Once the file is copied to SFTP,
+the original file from the Google Storage is deleted. The ``destination_path`` parameter defines the
+full path of the file on the SFTP server.
+
+.. exampleinclude:: ../../../../airflow/example_dags/example_gcs_to_sftp.py
+    :language: python
+    :dedent: 4
+    :start-after: [START howto_operator_gcs_to_sftp_move_single_file_destination]
+    :end-before: [END howto_operator_gcs_to_sftp_move_single_file_destination]
+
+
+Copying a directory
+-------------------
+
+Use the ``wildcard`` in ``source_path`` parameter to copy a directory.
+
+.. exampleinclude:: ../../../../airflow/example_dags/example_gcs_to_sftp.py
+    :language: python
+    :dedent: 4
+    :start-after: [START howto_operator_gcs_to_sftp_copy_directory]
+    :end-before: [END howto_operator_gcs_to_sftp_copy_directory]
+
+Moving specific files
+---------------------
+
+Use the ``wildcard`` in ``source_path`` parameter to move the specific files.
+The ``destination_path`` defines the path that is prefixed to all copied files.
+
+.. exampleinclude:: ../../../../airflow/example_dags/example_gcs_to_sftp.py
+    :language: python
+    :dedent: 4
+    :start-after: [START howto_operator_gcs_to_sftp_move_specific_files]
+    :end-before: [END howto_operator_gcs_to_sftp_move_specific_files]
+
+Reference
+^^^^^^^^^
+
+For further information, look at:
+
+* `Google Cloud Storage Documentation <https://cloud.google.com/storage/>`__

docs/operators-and-hooks-ref.rst

@@ -773,7 +773,7 @@ These integrations allow you to copy data from/to Google Cloud Platform.
 
    * - `Google Cloud Storage (GCS) <https://cloud.google.com/gcs/>`__
      - SFTP
-     -
+     - :doc:`How to use <howto/operator/gcp/gcs_to_sftp>`
      - :mod:`airflow.operators.gcs_to_sftp`