Licensing and Authorization

GeoAnalytics Engine must be authorized before running any tool or function. You can authorize the module with a GeoAnalytics Engine username and password, a GeoAnalytics Engine access token, 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.

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 three 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
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    import geoanalytics
    geoanalytics.auth(username="User1", password="p@ssw0rd")
    
  • Provide a token generated with your username and password.
    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
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    import geoanalytics
    geoanalytics.auth(token="983yr0qjddqewijdlsjdfljfwepwrr45")
    
  • Provide the path to a license file for offline 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
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    import geoanalytics
    geoanalytics.auth(license_file="C:\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. 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.token—An access token generated using the username and password for an active subscription to GeoAnalytics Engine.

  • spark.geoanalytics.auth.license.file—The path to a license file for offline authorization.

Verifying 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 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 online licensing.
  • 'authorized'—True if the module is correctly authorized and ready to use.

The following property is returned for offline licensing only:

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

The following properties are returned for online licensing only:

  • 'billing_type'—The plan type for online 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 online and offline licensing:

  • Online 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
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    
    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|
    +--------------+-------------+
  • Offline 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
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    import geoanalytics, time
    
    print("Before authorization:")
    geoanalytics.auth_info().show()
    
    geoanalytics.auth(license_file=r"C:\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|
    +--------------+------------+

Online authorization and usage reporting

If you authorize ArcGIS GeoAnalytics Engine with a username and password or a token, the runtime of any Spark job that includes ArcGIS GeoAnalytics Engine functionality will be measured in compute unit-milliseconds and will be reported to Esri and deducted from the available compute unit-hours or "core-hours" in your prepaid plan. Only the runtime of Spark jobs that include ArcGIS GeoAnalytics Engine functionality will be reported. If you authorized GeoAnalytics Engine with a license file, no usage is recorded or reported.

As an example, say you have a prepaid plan and you run a Spark job on a cluster with 60 cores for 1 minute. If that Spark job includes a GeoAnalytics Engine data source, SQL function, or tool, the total usage reported would be 60 cores times 60000 milliseconds for a total of 3600000 compute unit-milliseconds or 1.00 core-hours. This value is reported to Esri and is deducted from the available core-hours in your prepaid plan.

Usage is reported in the following scenarios if you authorized with a username and password or token:

  • Every five minutes if there is new usage data that has not been reported.
  • After a Spark job completes if more than 5 minutes have elapsed since the last time usage was reported.
  • After a Spark job completes if more than 1 core-hour is consumed.
  • When the Spark driver shuts down.
  • When you deauthorize GeoAnalytics Engine.

You can view your subscription's usage history and available core-hours online at the GeoAnalytics Engine dashboard. There may be a delay between when you consume core-hours and when those core-hours are shown as consumed in the dashboard. You can also query your subscription's usage history with the API at any time after authorizing using the usage function, geoanalytics.usage(). This function returns a DataFrame where each row represents your subscription's GeoAnalytics Engine usage during a period of time. The columns ComputeMillis and ComputeHours contain the amount of compute time used during each interval in cpu-milliseconds and cpu-hours respectively. The From and To columns contain the start and end time of each interval. Lastly, the Committed column shows whether or not the usage has been committed to your account. The example below shows what a DataFrame from geoanalytics.usage() might look like.

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
44
45
46
47
48
49
50
51
52
53
54
55
import geoanalytics
geoanalytics.auth(username="User1", password="p@ssw0rd")

geoanalytics.usage().show()
Result
Use dark colors for code blocksCopy
            
1
2
3
4
5
6
7
8
9
10
11
12
 +-------------+------------+--------------------+--------------------+---------+
|ComputeMillis|ComputeHours|                From|                  To|Committed|
+-------------+------------+--------------------+--------------------+---------+
|      4719873|      1.3111| 2022-01-10 10:00:00| 2022-01-10 11:00:00|     true|
|       470036|      0.1306| 2022-01-10 11:00:00| 2022-01-10 12:00:00|     true|
|       356497|      0.0990| 2022-01-10 12:00:00| 2022-01-10 13:00:00|     true|
|       295957|      0.0822| 2022-01-10 13:00:00| 2022-01-10 14:00:00|     true|
|            0|      0.0000| 2022-01-10 14:00:00| 2022-01-10 15:00:00|     true|
|            0|      0.0000| 2022-01-10 15:00:00| 2022-01-10 16:00:00|     true|
|            0|      0.0000| 2022-01-10 16:00:00| 2022-01-10 17:00:00|     true|
|          451|      0.0001|2022-01-10 16:02:...|2022-01-10 16:07:...|    false|
+-------------+------------+--------------------+--------------------+---------+

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().

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.