Skip to content

Commit 7883727

Browse files
bshafferbshaffer
committed
add getting-started
1 parent 3bc7a82 commit 7883727

2 files changed

Lines changed: 194 additions & 1 deletion

File tree

‎docs/devsite-help/getting-started.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Getting started with client libraries
2+
3+
The Google Cloud Libraries for Python are a mixture of handwritten and autogenerated
4+
libraries connecting to Google Cloud services. The handwritten libraries (such
5+
as [google-cloud-firestore](https://docs.cloud.google.com/python/docs/reference/firestore/latest) and
6+
[google-cloud-spanner](https://docs.cloud.google.com/python/docs/reference/spanner/latest))
7+
are mostly higher level abstractions over the underlying API. See the documentation
8+
for those individual libraries for details; the documentation here is primarily
9+
aimed at the autogenerated libraries.
10+
11+
If you haven't already found the library for the API you're interested in, please consult
12+
[the list of Python libraries](https://cloud.google.com/python/docs/reference) which shows both the package
13+
name and the link to the library-specific documentation. In particular, each library has:
14+
15+
- A "getting started" page which lists the client types within that library
16+
- Version history for the library
17+
- API reference documentation
18+
19+
This page demonstrates using the [google-cloud-translate](https://docs.cloud.google.com/python/docs/reference/translate/latest)
20+
API as a simple example; the steps required for other APIs are very similar.
21+
22+
## Prerequisites
23+
24+
All Google Cloud APIs require a Google Cloud project. If you haven't set one up already,
25+
please [create one](https://cloud.google.com/resource-manager/docs/creating-managing-projects).
26+
You'll also need to [enable your chosen API](https://console.cloud.google.com/apis/library) if it hasn't
27+
already been used within that Google Cloud project.
28+
29+
There are no specific tools required to develop using the Google Cloud Libraries for Python. All
30+
development environments should work, but you should check that you're targeting a
31+
[supported version of Python](https://docs.cloud.google.com/python/docs/supported-python-versions).
32+
33+
We recommend installing the [gcloud CLI](https://cloud.google.com/sdk/gcloud).
34+
35+
## Install the library
36+
37+
All Google Cloud Libraries for Python are available from [PyPI](https://pypi.org) and can be installed
38+
using `pip`. If you wish to install a pre-release version, you can specify the version explicitly
39+
with the installation command.
40+
41+
The libraries can be installed in any regular environment, including virtual environments (recommended),
42+
containerized applications, and web frameworks like Django or Flask.
43+
44+
For the translation example, we'll create a new directory, set up a virtual environment,
45+
and install the package.
46+
47+
Note that for simplicity, the sample code below uses synchronous calls. Most libraries also provide
48+
asynchronous clients (usually prefixed with `Async`) for use in naturally asynchronous environments
49+
using `asyncio`.
50+
51+
```sh
52+
mkdir TranslationExample
53+
cd TranslationExample
54+
python3 -m venv venv
55+
source venv/bin/activate
56+
pip install google-cloud-translate
57+
```
58+
59+
> **Dependencies**
60+
> If you install the library, you may notice
61+
> a lot of transitive dependencies being installed. This is entirely expected, but you may not recognize
62+
> some of those dependencies. The list below is not comprehensive, but highlights some of the packages
63+
> you'll see being installed.
64+
>
65+
> - protobuf: the library supporting the [Protocol Buffers](https://protobuf.dev) serialization format
66+
> - google-api-core: support libraries specifically tailored for the Google Cloud client libraries
67+
> - google-auth: authentication support for Google Cloud credentials
68+
> - grpcio: support for the [gRPC](https://grpc.io/) RPC protocol
69+
> - google-cloud-core: common helpers and support for [long-running operations](https://docs.cloud.google.com/python/docs/reference/google-cloud-core/latest)
70+
71+
## Create a client
72+
73+
The first step in making any API calls is to create a client. Some libraries have multiple clients
74+
for operations involving different resources; others have a single client. In the Translation API
75+
we're using, we use `TranslationServiceClient`.
76+
77+
Clients can be configured in a number of ways, but in many cases the defaults are fine. The most
78+
common reason to use explicit configuration is to use specific credentials for
79+
[authentication](https://cloud.google.com/docs/authentication/use-cases). For this example, we'll just use
80+
[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev).
81+
To set up ADC in your local environment, follow the instructions in
82+
[Local development environment](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev).
83+
When you create a client, it automatically detects and uses these credentials.
84+
85+
To create a client with default settings:
86+
87+
```python
88+
from google.cloud import translate_v3 as translate
89+
90+
client = translate.TranslationServiceClient()
91+
```
92+
93+
## Make requests
94+
95+
The Google Cloud Libraries use [Protocol Buffers](https://protobuf.dev)
96+
to represent requests and responses, with some additional types to make the APIs more
97+
convenient to work with.
98+
99+
Most APIs are expressed in terms of a single request returning a single response, although
100+
there are also some streaming APIs involving multiple requests and/or multiple responses.
101+
For our Translation API example, we'll create a simple request for the `translate_text` API.
102+
103+
```python
104+
from google.cloud import translate_v3 as translate
105+
106+
client = translate.TranslationServiceClient()
107+
108+
project_id = "your-project-id-here"
109+
location_id = "global"
110+
parent = f"projects/{project_id}/locations/{location_id}"
111+
request = translate.TranslateTextRequest(
112+
contents=["It is raining.", "It is sunny."],
113+
target_language_code="fr-FR",
114+
parent=parent
115+
)
116+
117+
response = client.translate_text(request=request)
118+
```
119+
120+
This example demonstrates a few features:
121+
122+
- Protocol Buffer messages are instantiated with keyword arguments representing the fields
123+
- Repeated fields (like `contents`) are represented as Python lists
124+
- The `parent` field is a string representation of a resource name. The library provides helper methods
125+
on the client to construct these paths, ensuring you don't need to concern yourself
126+
with the underlying resource name format.
127+
128+
The Google Cloud Libraries always expose methods accepting an API request object directly,
129+
but they also support passing keyword arguments directly to the method for convenience:
130+
131+
```python
132+
response = client.translate_text(
133+
contents=["It is raining.", "It is sunny."],
134+
target_language_code="fr-FR",
135+
parent=parent,
136+
)
137+
```
138+
139+
The response is also a Protocol Buffers message. You can inspect the structure of the response
140+
by printing it, or by accessing its attributes directly. In this case we'll look at the
141+
`translations` attribute:
142+
143+
```python
144+
print(f"Translations returned: {len(response.translations)}")
145+
print()
146+
for translation in response.translations:
147+
print(f"Detected language: {translation.detected_language_code}")
148+
print(f"Translated text: {translation.translated_text}")
149+
print()
150+
```
151+
152+
This produces output of:
153+
154+
```text
155+
Translations returned: 2
156+
157+
Detected language: en
158+
Translated text: Il pleut.
159+
160+
Detected language: en
161+
Translated text: Il fait beau.
162+
```
163+
164+
The complete code is:
165+
166+
```python
167+
from google.cloud import translate_v3 as translate
168+
169+
client = translate.TranslationServiceClient()
170+
171+
project_id = "your-project-id-here"
172+
location_id = "global"
173+
parent = f"projects/{project_id}/locations/{location_id}"
174+
175+
request = translate.TranslateTextRequest(
176+
contents=["It is raining.", "It is sunny."],
177+
target_language_code="fr-FR",
178+
parent=parent,
179+
)
180+
181+
response = client.translate_text(request=request)
182+
183+
print(f"Translations returned: {len(response.translations)}")
184+
print()
185+
for translation in response.translations:
186+
print(f"Detected language: {translation.detected_language_code}")
187+
print(f"Translated text: {translation.translated_text}")
188+
print()
189+
```
190+
191+
This is just a simple example, which hasn't touched on features like pagination
192+
or specifying call configurations like timeouts and retries.
193+

‎docs/devsite-help/noxfile.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
# Hardcoded dictionary of documentation files.
2525
# Format: {"Display Title": "filename.md" or absolute path}
2626
DOCS_MAP = {
27-
"Getting started": str(REPO_ROOT / "README.rst"),
27+
"Getting started": str(CURRENT_DIRECTORY / "getting-started.md"),
2828
}
2929

3030
nox.options.sessions = [

0 commit comments

Comments
 (0)