diff --git a/docs/docs-beta/docs/guides/external-systems/apis.md b/docs/docs-beta/docs/guides/external-systems/apis.md index 83ef36a292eb6..46696a5b69c64 100644 --- a/docs/docs-beta/docs/guides/external-systems/apis.md +++ b/docs/docs-beta/docs/guides/external-systems/apis.md @@ -26,16 +26,28 @@ To follow the steps in this guide, you'll need: Here is a minimal Resource for connecting to the an API that returns data about the sunrise and sunset times. In this example, the request URL has been hardcoded to query for data at San Francisco International Airport. - + ## Step 2: Use the Resource in an asset -To use the Resource written in step 1, you can provide it to an asset like this: +To use the Resource written in Step 1, you can provide it to an asset like this: - + + + +## Step 3: Configure your Resource +Many APIs have configuration you can set to customize your usage. Here is an updated version of the Resource from Step 1 with configuration to allow for setting the query location: + + + +## Step 4: Use the configurable Resource in an asset + +The configurable Resource written in Step 3 can be provided to an asset exactly as before. When the Resource is initialized, you can pass values for each of the configuration options. + + ## Next steps -- [Customize resources with configuration](/todo) +- [Authenticate to a resource](/guides/external-systems/authentication.md) - Learn what [dagster-provided Resources](/todo) are available to use diff --git a/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/configurable_resource.py b/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/configurable_resource.py new file mode 100644 index 0000000000000..d12bbc546e807 --- /dev/null +++ b/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/configurable_resource.py @@ -0,0 +1,17 @@ +import requests + +import dagster as dg + + +class SunResource(dg.ConfigurableResource): + latitude: float + longitude: float + time_zone: str + + @property + def query_string(self) -> str: + return f"https://api.sunrise-sunset.org/json?lat={self.latittude}&lng={self.longitude}&date=today&tzid={self.time_zone}" + + def sunrise(self) -> str: + data = requests.get(self.query_string, timeout=5).json() + return data["results"]["sunrise"] diff --git a/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/minimal_resource.py b/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/minimal_resource.py index 8c46bf060b9fe..fb6422e0c531f 100644 --- a/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/minimal_resource.py +++ b/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/minimal_resource.py @@ -8,8 +8,8 @@ class SFOSunResource(dg.ConfigurableResource): def query_string(self) -> str: latittude = 37.615223 longitude = -122.389977 - tzone = "America/Los_Angeles" - return f"https://api.sunrise-sunset.org/json?lat={latittude}&lng={longitude}&date=today&tzid={tzone}" + time_zone = "America/Los_Angeles" + return f"https://api.sunrise-sunset.org/json?lat={latittude}&lng={longitude}&date=today&tzid={time_zone}" def sunrise(self) -> str: data = requests.get(self.query_string, timeout=5).json() diff --git a/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_configurable_resource_in_asset.py b/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_configurable_resource_in_asset.py new file mode 100644 index 0000000000000..4150c426fbc34 --- /dev/null +++ b/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_configurable_resource_in_asset.py @@ -0,0 +1,36 @@ +import requests + +import dagster as dg + + +class SunResource(dg.ConfigurableResource): + latitude: float + longitude: float + time_zone: str + + @property + def query_string(self) -> str: + return f"https://api.sunrise-sunset.org/json?lat={self.latitude}&lng={self.longitude}&date=today&tzid={self.time_zone}" + + def sunrise(self) -> str: + data = requests.get(self.query_string, timeout=5).json() + return data["results"]["sunrise"] + + +# highlight-start +@dg.asset +def sfo_sunrise(context: dg.AssetExecutionContext, sun_resource: SunResource) -> None: + sunrise = sun_resource.sunrise() + context.log.info(f"Sunrise in San Francisco is at {sunrise}.") + + +defs = dg.Definitions( + assets=[sfo_sunrise], + resources={ + "sun_resource": SunResource( + latitude=37.615223, longitude=-122.389977, time_zone="America/Los_Angeles" + ) + }, +) + +# highlight-end diff --git a/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_resource_in_asset.py b/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_minimal_resource_in_asset.py similarity index 84% rename from examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_resource_in_asset.py rename to examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_minimal_resource_in_asset.py index e066ef6d7d3b1..ef2a93055fdc4 100644 --- a/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_resource_in_asset.py +++ b/examples/docs_beta_snippets/docs_beta_snippets/guides/external-systems/apis/use_minimal_resource_in_asset.py @@ -8,14 +8,15 @@ class SFOSunResource(dg.ConfigurableResource): def query_string(self) -> str: latittude = 37.615223 longitude = -122.389977 - tzone = "America/Los_Angeles" - return f"https://api.sunrise-sunset.org/json?lat={latittude}&lng={longitude}&date=today&tzid={tzone}" + time_zone = "America/Los_Angeles" + return f"https://api.sunrise-sunset.org/json?lat={latittude}&lng={longitude}&date=today&tzid={time_zone}" def sunrise(self) -> str: data = requests.get(self.query_string, timeout=5).json() return data["results"]["sunrise"] +# highlight-start @dg.asset def sfo_sunrise( context: dg.AssetExecutionContext, sun_resource: SFOSunResource @@ -27,3 +28,5 @@ def sfo_sunrise( defs = dg.Definitions( assets=[sfo_sunrise], resources={"sun_resource": SFOSunResource()} ) + +# highlight-end