Aceder ao App Engine com a API Remote

A CLI Google Cloud inclui um pacote remote_api que lhe permite aceder de forma transparente aos serviços do App Engine a partir de qualquer aplicação Go. Por exemplo, pode usar a API Remote para aceder ao Datastore a partir de uma app em execução no seu computador local ou a partir de outra das suas apps do App Engine.

Para ver o conteúdo do pacote remote_api, consulte a referência do remote_api pacote.

A ativar a API remota

Primeiro, adicione o controlador remote_api url ao seu app.yaml. Por exemplo:

- url: /_ah/remote_api
  script: _go_app

Isto mapeia o URL /_ah/remote_api para a sua app Go. O acesso a este URL está restrito aos administradores da aplicação pelo controlador da API remota.

Em seguida, importe o pacote remote_api num dos pacotes do seu projeto adicionando a seguinte linha a qualquer um dos seus ficheiros de origem .go:

import _ "google.golang.org/appengine/remote_api"

Durante a inicialização do programa, o pacote remote_api regista um controlador para o caminho /_ah/remote_api. O sublinhado na declaração de importação significa "importar este pacote, mas não o vamos usar diretamente". Sem o caráter de sublinhado, receberia uma mensagem de erro "importado, mas não usado" na compilação.

Por último, implementa a atualização no App Engine. Por exemplo:

gcloud app deploy app.yaml

Usar a API Remote num cliente local

A API Remote pode ser usada para escrever aplicações locais que usam os serviços do App Engine e acedem ao armazenamento de dados. É importante ter em atenção que a utilização da API Remote implica a utilização de quota na aplicação à qual está a aceder.

Antes de começar, certifique-se de que a API Remote está ativada na sua aplicação do App Engine. A aplicação local pode usar a API Remote criando um contexto com remote_api.NewRemoteContext e usando-o em vez do contexto normal do App Engine em todas as chamadas da API.

// Copyright 2011 Google Inc. All rights reserved.
// Use of this source code is governed by the Apache 2.0
// license that can be found in the LICENSE file.

package main

import (
	"log"
	"time"

	"golang.org/x/net/context"
	"golang.org/x/oauth2/google"

	"google.golang.org/appengine/datastore"
	"google.golang.org/appengine/remote_api"
)

func main() {
	const host = "<your-app-id>.appspot.com"

	ctx := context.Background()

	hc, err := google.DefaultClient(ctx,
		"https://www.googleapis.com/auth/appengine.apis",
		"https://www.googleapis.com/auth/userinfo.email",
		"https://www.googleapis.com/auth/cloud-platform",
	)
	if err != nil {
		log.Fatal(err)
	}

	remoteCtx, err := remote_api.NewRemoteContext(host, hc)
	if err != nil {
		log.Fatal(err)
	}

	q := datastore.NewQuery("Greeting").
		Filter("Date >=", time.Now().AddDate(0, 0, -7))

	log.Println(q.Count(remoteCtx))
}

Para executar este código, tem de obter estes pacotes:

$ go get google.golang.org/appengine/...
$ go get golang.org/x/oauth2/...

Tem de indicar o nome de anfitrião do seu servidor e um http.Client na chamada para NewRemoteContext. O http.Client fornecido é responsável por transmitir as informações de autenticação necessárias em cada pedido.

No exemplo acima, o DefaultClient do pacote golang.org/x/oauth2/google fornece credenciais do OAuth 2 através das Credenciais padrão da aplicação.

Limitações e práticas recomendadas

O módulo remote_api esforça-se por garantir que, na medida do possível, se comporta exatamente como o datastore do App Engine nativo. Em alguns casos, isto significa fazer coisas que são menos eficientes do que poderiam ser de outra forma. Quando usar a API remote_api, tenha em atenção o seguinte:

Cada pedido de armazenamento de dados requer um processo de ida e volta

Uma vez que está a aceder ao arquivo de dados através de HTTP, existe um pouco mais de sobrecarga e latência do que quando acede localmente. Para acelerar o processo e diminuir a carga, tente limitar o número de viagens de ida e volta que faz agrupando as obtenções e as colocações, e obtendo lotes de entidades a partir de consultas. Este é um bom conselho não só para a remote_api, mas também para a utilização da base de dados em geral, porque uma operação em lote é considerada uma única operação da base de dados.

Pedidos de utilização da quota da remote_api

Uma vez que a remote_api opera através de HTTP, cada chamada de datastore que fizer incorre na utilização da quota para pedidos HTTP, bytes de entrada e saída, bem como na quota de datastore habitual. Tenha isto em atenção se estiver a usar a API remote_api para fazer atualizações em massa.

Aplicam-se limites da API de 1 MB

Tal como quando são executados nativamente, o limite de 1 MB nas solicitações e respostas da API continua a aplicar-se. Se as suas entidades forem particularmente grandes, pode ter de limitar o número de entidades que obtém ou coloca de cada vez para se manter abaixo deste limite. Infelizmente, isto entra em conflito com a minimização das viagens de ida e volta. Por isso, a melhor recomendação é usar os maiores lotes possíveis sem exceder as limitações de tamanho de pedidos ou respostas. No entanto, é improvável que isto seja um problema para a maioria das entidades.

Evite iterar consultas

Quando itera sobre consultas, o SDK obtém entidades do arquivo de dados em lotes de 20, obtendo um novo lote sempre que usa os existentes. Uma vez que cada lote tem de ser obtido num pedido separado pela API remote_api, não é possível fazê-lo de forma tão eficiente. Em alternativa, a API remote_api executa uma consulta totalmente nova para cada lote, usando a funcionalidade de deslocamento para obter mais resultados.

Se souber de quantas entidades precisa, pode fazer toda a obtenção num único pedido pedindo o número de que precisa.

Se não souber quantas entidades quer, pode usar cursores para iterar de forma eficiente em grandes conjuntos de resultados. Isto também permite evitar o limite de 1000 entidades imposto nas consultas normais da base de dados.

As transações são menos eficientes

Para implementar transações através da remote_api, acumula informações sobre entidades obtidas na transação, juntamente com cópias de entidades que foram colocadas ou eliminadas na transação. Quando a transação é confirmada, envia todas estas informações para o servidor do App Engine, onde tem de obter novamente todas as entidades que foram usadas na transação, verificar se não foram modificadas, colocar e eliminar todas as alterações feitas pela transação e confirmá-la. Se existir um conflito, o servidor reverte a transação e notifica o cliente, que tem de repetir todo o processo.

Esta abordagem funciona e duplica exatamente a funcionalidade fornecida pelas transações no arquivo de dados local, mas é bastante ineficiente. Use transações sempre que necessário, mas tente limitar o número e a complexidade das transações que executa para aumentar a eficiência.