Authorization

GeoAnalytics Engine must be authorized with a valid license before running any tool or function. You can authorize the module with a GeoAnalytics Engine username and password, or a license file provided by Esri. If the module is not authorized, any tool or function will fail with com.esri.geoanalytics.internal.AuthError: Not authorized. For more information on GeoAnalytics Engine licenses, see Licensing.

You can authorize GeoAnalytics Engine in one of two ways:

• Call a Python function in a PySpark notebook, shell, or script.
• Set a property in the Spark configuration.

Authorize using Python

You can authorize GeoAnalytics Engine in a PySpark notebook, the PySpark shell, or in a script by importing the module and calling the authorization function, geoanalytics.auth(). The function arguments required depend on how you are authorizing the module. The two options are:

• Provide a username and password for an active GeoAnalytics Engine subscription. This securely authorizes GeoAnalytics Engine over the internet using OAuth 2.0.
  Python

  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  import geoanalytics
  geoanalytics.auth(username="User1", password="p@ssw0rd")
  
• Provide the path to a license file for disconnected authorization. The file must be accessible to the Spark driver.
  Python

  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  import geoanalytics
  geoanalytics.auth(license_file="/engine/license.ecp")
  
  

Authorize using Spark properties

You can also authorize GeoAnalytics Engine in the Spark configuration by setting one of three properties. These properties can be set using command line arguments, a config file, or directly on the SparkContext in a PySpark session. For more information see Spark configuration.

• spark.geoanalytics.auth.cred.file—The path to a file containing the username and password for an active GeoAnalytics Engine subscription. The file must be accessible to the Spark driver. This securely authorizes GeoAnalytics Engine over the internet using OAuth 2.0. For example:

  Use dark colors for code blocksCopy

  1
  2
  username User1
  password p@ssw0rd

• spark.geoanalytics.auth.license.file—The path to a license file for disconnected authorization. The file must be accessible to the Spark driver.

Verify authorization

You can verify that you are correctly authorized to use GeoAnalytics Engine by running any SQL function or tool, or by calling the authorization info function, geoanalytics.auth_info(). This function returns a DataFrame with two columns, name and value, which represent the name of user property and the value of that property respectively. The properties returned include:

• 'session_uptime'—The amount of time in milliseconds that GeoAnalytics Engine has been authorized in the current session.
• 'auth'—The type of authorization currently in use. Options are token/oauth or license/file.
• 'scope'—The scope of the current authorization.
• 'offline'—False if the module is connected for usage time reporting, otherwise True.
• 'metered'—True if usage time is being measured. Usage is measured in compute units per millisecond. Usage is only metered for connected licensing.
• 'authorized'—True if the module is correctly authorized and ready to use.

The following property is returned for disconnected licensing only:

• 'expires'—The date the disconnected license file expires.

The following properties are returned for connected licensing only:

• 'billing_type'—The plan type for connected licensing.
• 'session_usage'—The compute unit-milliseconds consumed in the current session.

If the module is not authorized, geoanalytics.auth_info() will return an empty DataFrame. The code snippet below shows an example of what the DataFrame returned from geoanalytics.auth_info() might look like before and 10 seconds after authorization for connected and disconnected licensing:

• Connected authorization:

  Python

  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  
  import geoanalytics, time
  
  print("Before authorization:")
  geoanalytics.auth_info().show()
  
  geoanalytics.auth(username="User1", password="p@ssw0rd")
  time.sleep(10)
  
  print("After authorization:")
  geoanalytics.auth_info().show()
  
  Result

  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  Before authorization:
  +----+-----+
  |name|value|
  +----+-----+
  +----+-----+
  
  After authorization:
  
  +--------------+-------------+
  |          name|        value|
  +--------------+-------------+
  |session_uptime|        10015|
  |          auth|  token/oauth|
  |         scope|      session|
  |       offline|         true|
  |       metered|         true|
  |    authorized|         true|
  |      username|        User1|
  |  billing_type|   PayAsYouGo|
  | session_usage|            0|
  +--------------+-------------+

• Disconnected authorization:

  Python

  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  import geoanalytics, time
  
  print("Before authorization:")
  geoanalytics.auth_info().show()
  
  geoanalytics.auth(license_file=r"/engine/license.ecp")
  time.sleep(10)
  
  print("After authorization:")
  geoanalytics.auth_info().show()
  Result

  Use dark colors for code blocksCopy

  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  Before authorization:
  +----+-----+
  |name|value|
  +----+-----+
  +----+-----+
  
  After authorization:
  
  +--------------+------------+
  |          name|       value|
  +--------------+------------+
  |session_uptime|       10015|
  |          auth|license/file|
  |         scope|     session|
  |       offline|        true|
  |       metered|       false|
  |    authorized|        true|
  |       expires|  2022-10-19|
  +--------------+------------+

Deauthorization

Once you authorize GeoAnalytics Engine, it will remain authorized until the Spark session is ended or until you call the deauthorization function, geoanalytics.deauth().